@layers/amba 1.1.0 → 4.0.2

package/README.md

@@ -38,7 +38,7 @@ After restarting your MCP client, paste:
 
 …to scaffold a full Expo app with Amba as the only backend. The skill
 fetches the canonical prompt from
-<https://docs.amba.dev/docs/prompts/expo-build> at invocation time and
+<https://docs.amba.dev/prompts/expo-build> at invocation time and
 falls back to an inlined snapshot when offline. Use `--no-skills` to
 skip the skill install.
 

package/dist/api-client.d.ts

@@ -20,6 +20,7 @@ export interface ProjectSummary {
     platform: string;
     environment?: string;
     bundle_id?: string | null;
+    google_oauth_client_id?: string | null;
     status?: string;
     created_at?: string;
 }
@@ -27,6 +28,12 @@ export declare function listProjects(): Promise<ApiListResponse<ProjectSummary>>
 export declare function createProject(input: {
     name: string;
     bundle_id?: string;
+    /**
+     * Google OAuth 2.0 client id. Doubles as the audience the server
+     * expects on Google Sign In id tokens — set this if your app uses
+     * Sign in with Google. Public identifier, not a secret.
+     */
+    google_oauth_client_id?: string;
     platform?: string;
     /**
      * Project environment. `'development'` flags the row as the developer's
@@ -40,6 +47,25 @@ export declare function createProject(input: {
     platform: string;
     environment?: string;
 }>>;
+/**
+ * PATCH /admin/projects/:projectId — update mutable fields. Server
+ * silently ignores unknown keys; we filter to the documented allow-list
+ * before sending so a typo at the CLI doesn't pass the wire silently.
+ */
+export declare function updateProject(projectId: string, patch: {
+    name?: string;
+    bundle_id?: string | null;
+    google_oauth_client_id?: string | null;
+    platform?: string;
+    environment?: string;
+}): Promise<ApiResponse<{
+    id: string;
+    name: string;
+    bundle_id: string | null;
+    google_oauth_client_id: string | null;
+    platform: string;
+    environment: string;
+}>>;
 export declare function getProject(projectId: string): Promise<ApiResponse<{
     id: string;
     name: string;
@@ -53,15 +79,16 @@ export declare function deleteProject(projectId: string): Promise<ApiResponse<{
     deleted: boolean;
 }>>;
 export declare function reprovisionProject(projectId: string): Promise<ApiResponse<{
-    workflowId?: string;
+    projectId: string;
+    job_id?: string;
     status?: string;
-    message?: string;
+    collapsed?: boolean;
 }>>;
 export declare function getProvisioningStatus(projectId: string): Promise<ApiResponse<{
     projectId: string;
     status: string;
-    workflowId?: string | null;
-    errorMessage?: string | null;
+    provisioned_at: string | null;
+    region: string | null;
 }>>;
 export declare function createApiKey(projectId: string, keyType: 'client' | 'server', environment: 'development' | 'production'): Promise<ApiResponse<{
     id: string;
@@ -521,8 +548,8 @@ export declare function dropCollection(projectId: string, name: string, confirm:
 export type AiProviderName = 'anthropic' | 'openai';
 export interface AiProviderRow {
     name: AiProviderName;
-    /** Canonical secret name in the secret store. NULL only mid-rotation. */
-    api_key_secret_name: string | null;
+    /** Whether an API key is currently configured for this provider. */
+    configured: boolean;
     /** Preview cue printed to the CLI on register; NOT a real partial key. */
     api_key_preview?: string;
     created_at?: string;

package/dist/auth.d.ts

@@ -37,6 +37,14 @@ export declare function clearCredentials(): Promise<void>;
  * `null` clears any prior override.
  */
 export declare function setBearerOverride(token: string | null): void;
+/**
+ * Read the current bearer override without consuming it. Returns
+ * `null` when no override is set. Used by commands that need to know
+ * "did the operator supply a PAT for this invocation?" — e.g. `init`
+ * branches on whether to bypass stored-creds and use the supplied
+ * token verbatim.
+ */
+export declare function getBearerOverride(): string | null;
 /** Test-only: reset the override between cases. */
 export declare function __resetTokenOverride(): void;
 /**

package/dist/bundle.d.ts

@@ -1,24 +1,38 @@
 /**
  * Customer-function bundling for `amba functions deploy`.
  *
- * Uses esbuild (the Workers ecosystem bundler-of-record). The shared
- * runtime stdlib is marked `external` so customer bundles don't
- * re-include megabytes of `@anthropic-ai/sdk`, `postgres`, `zod`, etc.;
- * these resolve at dispatch time via platform-level bindings.
+ * Uses esbuild. Customer code is bundled into a single self-contained
+ * ES module — the upstream runtime resolves nothing at dispatch time
+ * except built-in JavaScript globals.
  *
  * Two checks gate the bundle before upload:
  *   1. Pre-upload size check against `BUNDLE_MAX_SIZE_BYTES` (8 MB
  *      default — the platform's 10 MB compressed cap minus 2 MB
  *      headroom) with a clear error pointing at the externalization
  *      config.
- *   2. Bundle-shape report — the CLI prints what's externalized vs
- *      bundled at deploy time so size issues are debuggable.
+ *   2. Bundle-shape report — the CLI prints what's bundled vs
+ *      externalized at deploy time so size issues are debuggable.
+ *
+ * History note (2026-05-27): the prior version of this file pinned
+ * `@layers/amba-functions` + `@layers/amba-api-middleware` as
+ * "platform-level bindings" externals. Neither is — they were
+ * server-side packages, and `@layers/amba-functions` was unpublished
+ * in the 4.0.2 cutover (a deprecated wrapper that never matched the
+ * actual runtime). Any function importing one of them was rejected
+ * upstream as "no such module." The default externals list is now
+ * empty; customer code is expected to be self-contained.
  */
 import { type BuildOptions } from 'esbuild';
 /**
- * Modules customer code MUST externalize. The runtime exposes these as
- * platform-level bindings; bundling them per-script wastes hundreds of
- * KB to MBs and quickly hits the script-size cap.
+ * Modules the bundler treats as `external` by default. The Amba
+ * function runtime exposes zero npm packages — there is no "platform
+ * stdlib" for customer functions to import. Keep this list empty.
+ *
+ * The `extraExternals` field on `BundleOptions` is a programmatic
+ * escape hatch (used by tests + future CLI wiring). It's intentionally
+ * not exposed as a `amba functions deploy` flag today — externalizing
+ * a module that isn't actually provided at runtime is exactly the
+ * footgun this list-defaults-to-empty change closes.
  */
 export declare const RUNTIME_STDLIB_EXTERNALS: readonly string[];
 /**

package/dist/commands/billing.d.ts

@@ -0,0 +1,34 @@
+/**
+ * `amba billing *` subcommands — CLI access to the per-project billing
+ * surface that ships behind `/v1/admin/projects/:id/billing/*`.
+ *
+ *   amba billing status                    — tier, headroom on each
+ *                                            metered axis, next-bill date,
+ *                                            human_action_required.
+ *
+ *   amba billing upgrade --tier <t>        — print the Stripe Checkout
+ *                                            URL for tier ∈ {pro, scale}
+ *     [--interval month|year]               at the chosen interval. CLI
+ *                                            deliberately does NOT auto-
+ *                                            open a browser: agents pipe
+ *                                            the URL into a confirmation
+ *                                            step, humans copy-paste.
+ *
+ *   amba billing portal                    — print the Customer Portal
+ *                                            URL for card / cancel / etc.
+ *
+ *   amba billing set-ceiling <usd|off>     — cap (or remove) the monthly
+ *                                            spend ceiling.
+ *
+ * Project is resolved via `loadProjectConfig` (AMBA_PROJECT_ID env, then
+ * .env / .env.local in the cwd) — same pattern as `amba secrets *`.
+ */
+export declare function billingStatusCommand(): Promise<void>;
+export declare function billingUpgradeCommand(input: {
+    tier: 'pro' | 'scale';
+    interval?: 'month' | 'year';
+}): Promise<void>;
+export declare function billingPortalCommand(): Promise<void>;
+export declare function billingSetCeilingCommand(input: {
+    ceiling: number | null;
+}): Promise<void>;

package/dist/commands/claim.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `amba claim <email>` — bind a sandbox account to a real email address
+ * via a one-click magic link.
+ *
+ * Sandbox accounts are minted with an auto-generated address
+ * (`sandbox-<epoch>-<nonce>@layers.com`) and remain capped at 100 MAU /
+ * 10 MB DB until the developer claims a real email. This command POSTs
+ * the target email to `/v1/auth/developer/claim` under the developer's
+ * stored PAT; the backend emails a single-use magic link that — when
+ * clicked — updates the developer row and flips the project tier from
+ * `sandbox` to `verified_free` (1,000 MAU, 500 MB DB).
+ *
+ * Wire shape:
+ *
+ *   POST {AMBA_API_URL}/v1/auth/developer/claim
+ *   Authorization: Bearer {pat}
+ *   Content-Type: application/json
+ *   Body: { "email": "<target-email>" }
+ *
+ * Success: HTTP 200 `{ "ok": true }`
+ * Errors:  HTTP 400 INVALID_INPUT
+ *          HTTP 409 EMAIL_TAKEN     — that address already owns another account
+ *          HTTP 409 ALREADY_CLAIMED — this account is already verified
+ *          HTTP 429                  — rate-limited
+ *          HTTP 5xx                  — surface verbatim with code + message
+ *
+ * UX contract: a single ✓ line + a hint that the link expires in 15
+ * minutes. No copy-paste tokens, no follow-up commands. The click in
+ * the email is the whole flow.
+ */
+export interface ClaimCommandOptions {
+    /** Override the API root for tests + ops. Defaults to env or `https://api.amba.dev`. */
+    apiUrl?: string;
+    /** Inject a fetch implementation — test seam. */
+    fetchImpl?: typeof fetch;
+    /** Inject the developer PAT directly — test seam. Bypasses ~/.amba lookup. */
+    pat?: string;
+    /** Override `~/` resolution for credential lookup — test seam. */
+    homeDir?: string;
+}
+export declare function claimCommand(email: string, options?: ClaimCommandOptions): Promise<void>;

package/dist/commands/init.d.ts

@@ -40,42 +40,42 @@ export declare function runSandboxInit(cwd: string, options: {
     sandboxEmail?: string;
     noMcpConfig?: boolean;
     /**
-     * Skip the project-local `/amba-build` Claude Code skill install.
-     * Default is to install (the skill is what makes the agentic
-     * "/amba-build <design>" invocation work). Set true in CI or
-     * during tests that don't want stray files written into the
-     * caller's CWD.
+     * Skip the project-local skill install. Default is to install. Set
+     * true in CI or during tests that don't want stray files written.
      */
     noSkills?: boolean;
     json?: boolean;
     /**
      * Override `~/` resolution. The CLI itself never passes this — it's
      * the seam tests use to avoid touching the developer's actual home
-     * directory. (vi.spyOn can't intercept `os.homedir` under ESM, so
-     * dependency injection is the cleanest substitute.)
+     * directory.
      */
     homeDir?: string;
 }): Promise<SandboxResult>;
 /**
  * Build the plaintext (no ANSI) success-output block printed at the
- * end of `amba init --sandbox`. Pure function — exported only for the
- * vitest cases that assert on per-line content. The CLI wraps each
- * line with picocolors in `printSandboxNextSteps` below.
+ * end of `amba init --sandbox`. Pure function — exported for the
+ * vitest cases that assert on per-line content. The CLI wraps the
+ * output with picocolors in `printSandboxNextSteps` below.
  *
- * Structure (in order):
- *   1. Per-artifact checklist (`✓ ...` lines)
- *   2. SDK install + configure hint
- *   3. "Done." + per-client restart bullets — ONLY for clients we
- *      actually wrote configs to. Never instruct the user to "restart
- *      Cursor" if we only touched `~/.claude.json`. When no config
- *      was written (manual-paste path), falls back to a generic
- *      "quit + reopen" line.
- *   4. Tail-line resume hint + sandbox limits + verify URL.
+ * Design: silent-until-done. The install (provision account, mint
+ * keys, write .env.local, write MCP config, install skill) is COMPLETE
+ * the moment this output lands. The MCP config has been persisted —
+ * it activates on the next launch of the developer's coding agent. We
+ * do NOT instruct the developer to restart anything; we just state
+ * what's wired and what's next.
  *
- * We intentionally do NOT print any "kill -HUP / SIGHUP" advanced
- * workaround. Telling the agent to surface a clean "restart your MCP
- * client" instruction to the human is the whole optimization — adding
- * an experimental fallback just dilutes the signal and risks the
- * agent surfacing the workaround instead.
+ * Shape (~6 lines, Vercel/Stripe aesthetic):
+ *   ✓ Amba ready
+ *     project: <id>
+ *     keys → .env.local
+ *     mcp → <paths> (active next agent launch)
+ *     skill → <skill paths> (when installed)
+ *
+ *     next: npm install <sdk-pkg>
+ *           Amba.configure({ projectId, clientKey }) at app startup
+ *
+ * The fallback for "no MCP client config detected" is a one-line
+ * note + a paste-ready snippet — still no restart copy.
  */
 export declare function buildSandboxNextStepsLines(r: SandboxResult): string[];

package/dist/commands/projects.d.ts

@@ -3,8 +3,16 @@ export declare function projectsCreateCommand(input: {
     name: string;
     env?: string;
     bundleId?: string;
+    googleOauthClientId?: string;
     platform?: string;
 }): Promise<void>;
+export declare function projectsUpdateCommand(projectId: string, input: {
+    name?: string;
+    bundleId?: string;
+    googleOauthClientId?: string;
+    platform?: string;
+    environment?: string;
+}): Promise<void>;
 export declare function projectsShowCommand(projectId: string): Promise<void>;
 export declare function projectsDeleteCommand(projectId: string, opts?: {
     yes?: boolean;

package/dist/credentials.d.ts

@@ -0,0 +1,259 @@
+/**
+ * Two-scope credential model for `amba init`.
+ *
+ * Identity is **developer-scoped** (one machine identity, persisted in
+ * `~/.amba/credentials.json`). State is **project-scoped** (one per
+ * project directory, persisted in `<cwd>/.amba/project.json`).
+ *
+ * One Amba account can own N projects. Running `amba init` in five
+ * different folders under one identity yields one developer row + five
+ * project rows — exactly the model `apps/console` and the API enforce.
+ *
+ * Backward compatibility
+ * ----------------------
+ * The legacy `~/.amba/credentials.json` (browser-OAuth era) carried
+ * `{ access_token, refresh_token, expires_at }`. We read both shapes —
+ * a missing `version` key signals legacy and triggers a one-shot
+ * in-place upgrade after the first successful `developer_me` verify.
+ *
+ * Idempotency
+ * -----------
+ * `ensureDeveloperIdentity` + `ensureProjectForCwd` are the two entry
+ * points. Both are safe to call on every `amba init` run:
+ *   - identity: load → verify → upgrade-or-keep; only signs up if no
+ *     verified PAT exists anywhere.
+ *   - project: load `<cwd>/.amba/project.json` → verify the
+ *     `project_id` still belongs to the current developer; if missing
+ *     or stale, mint a new project under the dev's identity.
+ */
+/**
+ * Developer identity stored at `~/.amba/credentials.json`.
+ *
+ * One per machine. Persists across project folders and re-runs.
+ */
+export interface DeveloperCredentials {
+    /** Schema version — increments when the shape changes incompatibly. */
+    version: 1;
+    /** Developer UUID from the control DB. Populated post-verify. */
+    developer_id: string | null;
+    /** Email on the developer row. May be auto-generated for sandbox accounts. */
+    email: string;
+    /** Personal Access Token (`amb_dpat_…`). Long-lived. */
+    pat: string;
+    /** API root the PAT was minted against. */
+    api_url: string;
+    /** How this identity was created. */
+    source: 'sandbox-init' | 'browser-auth' | 'manual' | 'legacy';
+    /** ISO timestamp when this record was written/upgraded. */
+    created_at: string;
+    /** Mirrors `pat`. */
+    access_token: string;
+    /** Empty string — PATs don't refresh. */
+    refresh_token: '';
+    /** Far-future ISO timestamp — PATs don't expire on the client side. */
+    expires_at: string;
+}
+/**
+ * Project state stored at `<cwd>/.amba/project.json`.
+ *
+ * One per project directory. Tracks which project this folder is
+ * attached to (so re-running `amba init` in the same folder is
+ * idempotent) plus the credentials needed for SDK init.
+ */
+export interface ProjectCredentials {
+    version: 1;
+    project_id: string;
+    project_name: string;
+    environment: 'development' | 'production';
+    client_key: string;
+    /** Server key — present when minted. Used by Node SDK / server code. */
+    server_key: string | null;
+    api_url: string;
+    /**
+     * List of Amba surfaces this project has been wired up with via the
+     * skill (e.g. `['identity','streaks','achievements']`). The skill
+     * consults this on re-runs to avoid re-creating existing resources.
+     */
+    wired_surfaces: string[];
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Result returned by `verifyPat`. Subset of the API's
+ * `GET /v1/auth/developer/me` response — only the fields the CLI
+ * actually consumes.
+ */
+export interface DeveloperMeResult {
+    id: string;
+    email: string;
+    name?: string;
+}
+export declare function developerCredentialsPath(homeDir?: string): string;
+export declare function projectCredentialsPath(cwd: string): string;
+/**
+ * Read `~/.amba/credentials.json`. Returns null when the file is
+ * missing, malformed, or empty. Handles both new (versioned) and
+ * legacy shapes — legacy returns `version: 1` after migration but
+ * with `source: 'legacy'` so callers can tell.
+ *
+ * Does NOT verify the PAT against the API. Caller must follow up
+ * with `verifyPat` before trusting the identity.
+ */
+export declare function loadDeveloperCredentials(options?: {
+    homeDir?: string;
+}): Promise<DeveloperCredentials | null>;
+/**
+ * Atomically write developer credentials to `~/.amba/credentials.json`
+ * with mode 0600. Writes to a sibling `.tmp` first and renames into
+ * place so a crash mid-write doesn't leave the file empty.
+ *
+ * Backs up an existing file when its `source` is not one of the
+ * managed sources OR when the existing PAT differs from the one being
+ * written. The backup goes to `credentials.json.bak-<unix-ms>`.
+ */
+export declare function writeDeveloperCredentials(creds: DeveloperCredentials, options?: {
+    homeDir?: string;
+}): Promise<{
+    path: string;
+    backedUpTo: string | null;
+}>;
+export declare function loadProjectCredentials(cwd: string): Promise<ProjectCredentials | null>;
+export declare function writeProjectCredentials(cwd: string, creds: ProjectCredentials): Promise<string>;
+/**
+ * Verify a PAT by calling `GET /v1/auth/developer/me`. Returns the
+ * developer row on success, `null` on 401/403/404 (PAT invalid or
+ * developer not found), or throws on network / 5xx errors.
+ *
+ * This is the single source of truth for "do we have a working
+ * identity." Used at the top of every init run.
+ */
+export declare function verifyPat(pat: string, options?: {
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+}): Promise<DeveloperMeResult | null>;
+export interface EnsureDeveloperOptions {
+    homeDir?: string;
+    apiUrl?: string;
+    fetchImpl?: typeof fetch;
+    /**
+     * When true, never call signup — if the existing credential is
+     * invalid, throw instead. Used by the interactive (non-headless)
+     * init path where the user expects a browser-auth fallback.
+     */
+    signupOnMissing?: boolean;
+    /**
+     * Optional override for the auto-generated sandbox email. Surfaced
+     * by the CLI's `--email <addr>` flag for tests + manual sandbox
+     * provisioning under a known address. Ignored when an existing
+     * identity is reused.
+     */
+    sandboxEmail?: string;
+}
+export interface EnsureDeveloperResult {
+    credentials: DeveloperCredentials;
+    /** True when we minted a fresh sandbox account this run. */
+    newlySignedUp: boolean;
+    /** Verified developer row from the API. */
+    developer: DeveloperMeResult;
+    /**
+     * The first project minted by signup, when `newlySignedUp` is true.
+     * Null when we re-used an existing identity — caller is expected to
+     * mint a new project under it via `ensureProjectForCwd`.
+     */
+    firstProject: {
+        project_id: string;
+        client_key: string;
+        server_key: string | null;
+        provisioning_status?: string;
+        verify_url?: string;
+    } | null;
+    /**
+     * Absolute path of a backup file written when an existing credential
+     * was overwritten with a new one (different PAT). Null when no backup
+     * was needed (no prior file, same PAT verified, etc.).
+     */
+    credentialsBackedUpTo: string | null;
+    /** Absolute path of `~/.amba/credentials.json`. */
+    credentialsPath: string;
+}
+/**
+ * Ensure the machine has a verified Amba developer identity.
+ *
+ * Decision tree:
+ *   1. Load existing `~/.amba/credentials.json`.
+ *   2. If found, verify the PAT via `developer/me`.
+ *      - Valid → migrate shape if legacy, return.
+ *      - Invalid → fall through to signup (unless `signupOnMissing: false`).
+ *   3. No creds (or invalid) + `signupOnMissing !== false` → call
+ *      `performSandboxSignup` with generated email/password, write the
+ *      result, return.
+ *   4. No creds + `signupOnMissing === false` → throw.
+ */
+export declare function ensureDeveloperIdentity(options?: EnsureDeveloperOptions): Promise<EnsureDeveloperResult>;
+export interface EnsureProjectOptions {
+    /** Inject the dev-identity PAT into the api-client. */
+    pat: string;
+    /**
+     * When provided, attach this folder to the named project ID
+     * instead of creating a new one (e.g. user passed `--project-id`).
+     */
+    attachToProjectId?: string;
+    /**
+     * Default project name when minting. Defaults to `basename(cwd)`.
+     */
+    defaultName?: string;
+    /** `'development'` (default) or `'production'`. */
+    environment?: 'development' | 'production';
+    /**
+     * Optional pre-minted first-project payload from a sandbox-signup
+     * response. When provided AND no project.json exists yet, we use
+     * this without an extra `createProject` call. Saves a round-trip
+     * on the first-ever init.
+     */
+    signupFirstProject?: {
+        project_id: string;
+        client_key: string;
+        server_key: string | null;
+    };
+}
+export interface EnsureProjectResult {
+    credentials: ProjectCredentials;
+    /** True when we minted a new project this run. */
+    newlyCreated: boolean;
+}
+/**
+ * Ensure the current working directory is attached to an Amba project.
+ *
+ * Decision tree:
+ *   1. Load existing `<cwd>/.amba/project.json`.
+ *      - Present → return (no API call; we trust the file's metadata
+ *        until something downstream fails, at which point the caller
+ *        re-keys).
+ *   2. Missing + `signupFirstProject` provided → use those keys, write
+ *      `<cwd>/.amba/project.json`, return (newlyCreated=true).
+ *   3. Missing + no signup payload + `attachToProjectId` provided →
+ *      mint a new client+server key under that project, write the
+ *      file, return.
+ *   4. Missing + no signup payload + no attach → call
+ *      `createProject({ name, environment })` under the dev's PAT,
+ *      mint both keys, write the file, return.
+ */
+export declare function ensureProjectForCwd(cwd: string, options: EnsureProjectOptions): Promise<EnsureProjectResult>;
+/**
+ * Sanitize a candidate project name. The control-plane enforces
+ * `^[a-zA-Z0-9-_]{1,64}$` (see `apps/api/src/routes/projects.ts`); the
+ * basename of a project folder often contains spaces or dots. We
+ * collapse runs of non-allowed chars to `-`, trim outer dashes, and
+ * truncate to 64.
+ */
+export declare function sanitizeProjectName(input: string): string;
+/**
+ * Update an existing `<cwd>/.amba/project.json` to record additional
+ * surfaces the skill has wired up. Used by the Amba skill after each
+ * `amba_<surface>_create` call lands so re-runs can skip already-done
+ * work. Bumps `updated_at`. Silently no-ops if the file is missing
+ * (skill should always run after `amba init`).
+ */
+export declare function recordWiredSurface(cwd: string, surface: string): Promise<void>;
+/** True iff a `<cwd>/.amba/project.json` exists and parses. */
+export declare function projectIsLinked(cwd: string): Promise<boolean>;