Skip to content

Collector: partner API (a partner's server makes an app per user and reads what it finds) - #242

Open
MeharPro wants to merge 1 commit into
mainfrom
feat/partner-api
Open

MeharPro wants to merge 1 commit into
mainfrom
feat/partner-api

Conversation

@MeharPro

Copy link
Copy Markdown
Contributor

A partner API for products that set GenClass up for their own users (a coding-agent tool, a hosting or app-builder platform). The partner's server makes a GenClass app for each of its users, its agent puts the app's key in that user's code (npx @genclass/runtime@beta init --token <key>, no sign-in needed), and it reads what the app finds. The partner's account carries the apps and their plan, so its users need no GenClass account.

Who can use it. Only an account GenClass makes a partner by hand: the Enterprise grant plus accounts.partner_apps, how many apps it may hold (README "Partner API" has the SQL). Without that, every partner route answers 403 and /account shows nothing new.

Routes (Authorization: Bearer gcp_..., server to server):

  • POST /api/partner/v1/apps, body { ref, name? }: makes the app for that user (201), or returns the one already made for that ref (200). Stops at partner_apps with a 409.
  • GET /api/partner/v1/apps?ref=&cursor=: the apps it made, 100 a page.
  • GET /api/partner/v1/apps/<id>?range=: the app's dashboard as data, the same answer and plan rules as /api/cli/app, now shared through appView.
  • GET /api/partner/v1/apps/<id>/events: the existing export (exportFor).
  • POST /api/partner/v1/apps/<id>/link: a private dashboard link to hand that user. The previous link stops working.
  • /api/account/partner-keys: the browser session on genclass.dev makes, lists and revokes up to 10 keys. A new "Partner API" section in /account settings does this, and shows a key only once.

Rules:

  • A key reaches only its own account's apps; any other id is 404.
  • A cookie, a terminal session or an export key is never accepted as a partner key.
  • The routes send no CORS headers, so a key can't be used from a page in a browser.
  • A key stops working at once when it is revoked or the account stops being a partner.
  • Nothing here deletes an app.
  • Every route counts against the account's per-minute budget (EXPORT_LIMIT, bucket partner).
  • Deleting the account removes its partner keys. An app that keeps a private link leaves without its partner_ref.

Migration 0023 (additive): accounts.partner_apps, projects.partner_ref with a partial unique index on (account, ref), and the partner_keys table. It must be applied before deploying.

PRIVACY.md gets a short "Partners" section: a partner reads the apps it made as any account reads its own. Who receives an app's data is the owner's call, so it needs the owner's OK.

Tests and checks:

  • New test/partner.test.ts (8 tests).
  • The full collector suite passes (887 tests).
  • The CLI suite passes (207 tests), since /api/cli/app now goes through the shared appView.
  • tsc --strict on the worker is clean.
  • Migration 0023 applies to a local D1. On wrangler dev, I made a key in /account, then via curl: created an app (and got the same app for a repeated ref), sent it a batch, and read its view (no CORS headers), list, events and private link.

Not done here, and each needs the owner: merging, applying 0023 in production, deploying, and making the first partner account.

🤖 Generated with Claude Code

…reads what it finds)

An account GenClass makes a partner by hand (accounts.partner_apps, with the Enterprise grant) gets
partner keys on /account and five server-to-server routes under /api/partner/v1: make the app for a
user's ref (idempotent), list them, read one app's dashboard data and events, and hand that user a
private dashboard link. Keys are gcp_ + 32 bytes, hashed, browser-made, no CORS; a key reaches its
own account's apps only and stops when revoked or when the account stops being a partner. Nothing
deletes an app. Migration 0023 (partner_apps, projects.partner_ref, partner_keys).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant