authors

Overview ¶

Package authors is a royalty for open-source work: your repo runs, you get paid.

An author links GitHub, proves they own a repo, and earns a royalty on the metered spend of every org that deploys a project built from it — accrued per period and auto-paid, with a full audit trail behind the number.

It is the CREATOR member of the three programs built on the same shape; apps/referrals is the one-time bonus and apps/affiliates the partner commission. All three share the commerce ledger path (a credits payout is a grant, tag grant:author).

The loop, end to end:

1. An author CONNECTS GitHub (POST /v1/authors/connect): we link the caller's org to a GitHub login — from IAM's linked GitHub account when available (identity verified), else a login the caller supplies (verified per-repo below). We mint a stable per-author VERIFY CODE for the file method.
2. The author VERIFIES a repo (POST /v1/authors/repos/verify): ownership is proven either by an IAM-linked GitHub token showing ADMIN/PUSH permission on the repo (OAuth method), or by a hanzo.json on the repo's default branch carrying the author's verify code (file method — proves default-branch control). A verified repo can now earn.
3. When a published project whose sourceRepo matches a VERIFIED author repo is DEPLOYED by ANY org, the deploy path records it (POST /v1/authors/deploys/ record): deploying_org↔repo↔project, idempotent per (repo, project, org). hanzo.app persists sourceRepo on the published project so the deploy is attributable.
4. The ACCRUAL SWEEP (the scheduler's automatic loop; POST /v1/admin/authors/sweep as an operator override; also lazy on the author's own dashboard read) folds over each approved author's DISTINCT deploying orgs (excluding the author's own): royalty = that org's metered spend THIS PERIOD × the author's share (20%), accrued at-most-once per (author, deploying_org, period).
5. The AUTO-PAYOUT (same scheduler pass, right after accrual; POST /v1/admin/authors/:id/payout as an operator override) settles each author's pending royalty with NO human in the loop: "credits" issues a commerce grant into an external author's wallet; a Hanzo-MAINTAINED template's royalty is realized into the Hanzo treasury reserve instead ("pay ourselves"). A payout can never exceed pending (accrued − paid), guarded atomically — idempotent, never double-pays.

HANZO FORKS. A repo whose owner is a brand org (owner ∈ {hanzoai, hanzo-*}) is auto-attributed on first deploy to the treasury SYSTEM author (org = the brand slug), so Hanzo earns 20% on its OWN templates when other orgs deploy them, credited to the treasury reserve via the shared treasury client — no external wallet, no new ledger.

Surface:

GET  /v1/authors                       (org)          my status, login, verified, repos, deploys, accrued/pending/paid, payouts
GET  /v1/authors/basis                 (org)          why my number is my number: share, cost model, immutable rows, reconciliation
POST /v1/authors/connect               (org)          link GitHub (IAM-linked account or supplied login) + mint verify code
POST /v1/authors/repos/verify          (org)          verify repo ownership (oauth admin-check OR hanzo.json file)
POST /v1/authors/deploys/record        (org=deployer) record a deploy of a verified author repo (provenance → royalty)
GET  /v1/admin/authors                  (SuperAdmin) every author + a summary
POST /v1/admin/authors/sweep            (SuperAdmin) accrue royalty for every deploying org this period
POST /v1/admin/authors/:id/approve      (SuperAdmin) admit to earning (+ optional share override)
POST /v1/admin/authors/:id/suspend      (SuperAdmin) suspend
POST /v1/admin/authors/:id/payout       (SuperAdmin) record a payout (credits → grant; cash → record-only)
GET  /v1/admin/authors/:id/basis        (SuperAdmin) the SAME basis payload the author reads (support mirror)

serve.go auto-registers GET /v1/authors/health.