@layers/amba 1.0.1 → 4.0.2

package/README.md

@@ -1,13 +1,11 @@
-# `@layers/amba` — the amba CLI
+# @layers/amba
 
-amba is an agent-native backend-as-a-service for mobile apps: functions,
-collections, storage, AI, queues, and static sites — one CLI to spin up
-your project and ship to production.
+Amba is the agent-native backend-as-a-service for mobile and web apps. This package is the `amba` command-line interface.
 
 ## Install
 
 ```bash
-npm install -g @layers/amba
+npm install -g @layers/amba@1.0.1
 ```
 
 …or run on demand:
@@ -16,40 +14,65 @@ npm install -g @layers/amba
 npx @layers/amba init
 ```
 
-## Quick start
+Requires Node.js 22 or newer.
+
+## Agent mode (recommended)
+
+For AI coding agents (Claude Code, Cursor, Windsurf): one command, no
+browser, no prompts.
 
 ```bash
-amba init                  # mint a personal dev project and scaffold context
-amba login                 # authenticate (browser flow)
-amba projects list         # list projects you own
-amba projects create --name my-app
+npx @layers/amba init --sandbox
+```
+
+This signs up an agent-mode developer account, provisions a project,
+writes `.env.local` + `AMBA.md`, auto-wires `mcpServers.amba` into
+every MCP client config it finds on disk, and installs the
+`/amba-build` Claude Code skill at `.claude/skills/amba-build/SKILL.md`.
+
+After restarting your MCP client, paste:
+
+```
+/amba-build <design-url-or-description>
+```
+
+…to scaffold a full Expo app with Amba as the only backend. The skill
+fetches the canonical prompt from
+<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.
+
+## Configure + first call
+
+```bash
+amba init              # mint a personal project and write .amba/ config
+amba login             # browser-based auth (skip with --token / AMBA_PAT)
+amba projects list
+```
+
+Track your first event from the CLI:
+
+```bash
+amba events track app_opened --prop source=cli
 ```
 
 ## Common commands
 
 ```bash
 amba functions deploy ./functions/hello.ts
-amba functions list
-amba functions schedule hello "0 * * * *" --tz UTC
-
 amba collections create messages --field user_id:uuid --field body:text
-amba collections list
-amba types generate                # emit .amba/types.d.ts
-
+amba types generate                       # emits .amba/types.d.ts
 amba secrets set OPENAI_KEY --function hello --from-stdin
-
 amba sites deploy ./out --name marketing
-amba sites domain add marketing.example.com --site marketing
 ```
 
 ## Headless / CI
 
-Pass a personal access token via `--token <pat>` or the `AMBA_PAT` env
-var to skip the browser-based login flow.
+Pass a Personal Access Token via `--token <pat>` or `AMBA_PAT` to skip the browser login.
 
-## Requirements
+## Docs
 
-- Node.js 22+
+Full reference: <https://docs.amba.dev/cli>.
 
 ## License
 

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;
@@ -245,16 +272,16 @@ export interface FunctionDeploymentRow {
     project_id: string;
     name: string;
     version: number;
-    cf_script_name: string;
-    cf_dispatch_namespace: string;
+    runtime_script_name: string;
+    runtime_namespace: string;
     bundle_sha: string;
     status: 'active' | 'superseded' | 'disabled';
     created_at: string;
 }
 export declare function recordFunctionDeployment(projectId: string, input: {
     name: string;
-    cf_script_name: string;
-    cf_dispatch_namespace: string;
+    runtime_script_name: string;
+    runtime_namespace: string;
     bundle_sha: string;
     /**
      * Optional declarative rate-limit. The CLI passes a validated
@@ -298,13 +325,6 @@ export interface FunctionDeployContext {
      * step skips the storage binding in that case.
      */
     r2_bucket_name: string | null;
-    /**
-     * Cloudflare Hyperdrive config id. NULL until storage provisioning
-     * completes; deploy step skips the Hyperdrive binding when null and
-     * `ctx.collections` returns `tenant_unavailable` until the column is
-     * populated.
-     */
-    cf_hyperdrive_config_id: string | null;
 }
 export declare function getFunctionDispatchNamespace(projectId: string): Promise<ApiResponse<FunctionDeployContext>>;
 export interface InternalCredentialsResponse {
@@ -528,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;
@@ -548,7 +568,7 @@ export interface SiteRow {
     id: string;
     project_id: string;
     name: string;
-    cf_pages_project_name: string;
+    slug: string;
     status: 'active' | 'disabled' | 'archived';
     created_at: string;
     updated_at: string;
@@ -557,7 +577,7 @@ export interface SiteDomainRow {
     id: string;
     site_id: string;
     hostname: string;
-    cf_hostname_id: string | null;
+    provider_hostname_id: string | null;
     cert_status: 'pending_validation' | 'pending_issuance' | 'pending_deployment' | 'active' | 'error';
     created_at: string;
     updated_at: string;
@@ -589,18 +609,18 @@ export declare function archiveSite(projectId: string, name: string, confirm: st
 /** Cascade summary returned by site/function delete proxies. */
 export interface DeleteCascadeSummary {
     domains_removed?: number;
-    cf_pages_project_deleted?: boolean;
-    cf_dispatch_script_deleted?: boolean;
+    site_runtime_removed?: boolean;
+    runtime_script_removed?: boolean;
     function_deployments_marked_disabled?: number;
 }
 /**
  * Add a custom domain to a site. The server-side proxy registers the
- * custom hostname, persists the resulting `cf_hostname_id`, and returns
+ * custom hostname, persists the resulting `provider_hostname_id`, and returns
  * the CNAME target the customer should point their DNS at.
  */
 export declare function addSiteDomainViaApi(projectId: string, siteName: string, hostname: string): Promise<ApiResponse<{
     hostname: string;
-    cf_hostname_id: string;
+    provider_hostname_id: string;
     cert_status: SiteDomainRow["cert_status"];
     dns_target: string;
     created_at: string;
@@ -615,10 +635,10 @@ export declare function removeSiteDomainViaApi(projectId: string, siteName: stri
     deleted: true;
 }>>;
 /**
- * Roll a live CF Pages deployment back to a prior `deployment_id`. CF's
- * rollback creates a NEW deployment that serves the prior bundle (git-
- * revert semantics, not git-reset), so the response shape mirrors
- * `DeploySiteResult` and the new `deployment_id` is what's now live.
+ * Roll a live deployment back to a prior `deployment_id`. Rollback creates
+ * a NEW deployment that serves the prior bundle (git-revert semantics,
+ * not git-reset), so the response shape mirrors `DeploySiteResult` and
+ * the new `deployment_id` is what's now live.
  */
 export declare function rollbackSiteViaApi(projectId: string, siteName: string, deploymentId: string): Promise<ApiResponse<DeploySiteResult>>;
 /**
@@ -650,12 +670,12 @@ export declare function deleteFunctionViaApi(projectId: string, functionName: st
 }>>;
 export declare function attachSiteDomain(projectId: string, siteName: string, input: {
     hostname: string;
-    cf_hostname_id?: string;
+    provider_hostname_id?: string;
 }): Promise<ApiResponse<SiteDomainRow>>;
 export declare function listSiteDomains(projectId: string, siteName: string): Promise<ApiListResponse<SiteDomainRow>>;
 export declare function updateSiteDomain(projectId: string, siteName: string, hostname: string, patch: {
     cert_status: SiteDomainRow['cert_status'];
-    cf_hostname_id?: string;
+    provider_hostname_id?: string;
 }): Promise<ApiResponse<SiteDomainRow>>;
 export declare function detachSiteDomain(projectId: string, siteName: string, hostname: string): Promise<ApiResponse<{
     deleted: boolean;

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/functions.d.ts

@@ -32,11 +32,36 @@ export declare function functionsDeleteCommand(name: string, options?: {
 export declare function functionsScheduleCommand(name: string, cron: string, options?: {
     tz?: string;
 }): Promise<void>;
+export interface DevOptions {
+    /** Local port. Default 8787 (overridable per project). */
+    port?: number;
+    /** Don't watch the file for changes. Default false. */
+    noWatch?: boolean;
+}
 /**
- * `amba functions dev` — not configured in this release. Use
- * `amba functions deploy <file>` to deploy via the platform API.
+ * `amba functions dev <file>` — run the function locally with file-change
+ * hot reload.
+ *
+ * Architecture: the CLI process owns the file watcher + bundler; the
+ * actual HTTP server lives in a child Node process that imports the
+ * bundle and binds to the user's port. On file change, the parent kills
+ * the child, writes a fresh bundle, and respawns. This bounds memory
+ * (each rebuild = fresh V8 heap) and isolates customer-handler crashes
+ * from the CLI. Brief downtime per rebuild (~100ms while the port is
+ * released and re-bound); incoming connections during the swap queue
+ * at the TCP listen backlog and complete once the new child is up.
+ *
+ * The bundler is the same esbuild pipeline `amba functions deploy` uses
+ * — externalization rules, size cap, and source-map handling are
+ * identical so dev → prod parity is automatic.
+ *
+ * Handler shape: `export default async function (req: Request): Promise<Response>`.
+ * `.env.local` values in the customer's working directory are passed
+ * through to the child process so the handler can read them via
+ * `process.env.MY_KEY`. Existing values in the parent's env take
+ * priority (so `MY_KEY=x amba functions dev …` wins).
  */
-export declare function functionsDevCommand(_entryPoint: string): Promise<void>;
+export declare function functionsDevCommand(entryPoint: string, options?: DevOptions): Promise<void>;
 /**
  * `amba functions consume <queue> <function>` — bind a function as the
  * consumer for a queue. Customers send to a queue with `ctx.queue.send`;

package/dist/commands/init.d.ts

@@ -1,3 +1,4 @@
+import { type SandboxResult } from '../sandbox.js';
 export interface InitOptions {
     withExample?: boolean;
     /**
@@ -8,5 +9,73 @@ export interface InitOptions {
      * minted via `amba projects create --env production` by automation).
      */
     env?: 'development' | 'production';
+    /**
+     * Headless agentic mode. Skips browser auth + interactive prompts:
+     * the CLI generates a sandbox email + password, posts to
+     * `/v1/auth/developer/signup`, writes credentials everywhere
+     * (`~/.amba/credentials.json` + `.env.local` + `AMBA.md`), and
+     * auto-wires the Amba MCP server into every detected MCP client
+     * config. Designed to be invoked unattended by an AI coding agent
+     * that pasted the homepage 3-line prompt.
+     */
+    sandbox?: boolean;
+    /** Override the auto-generated sandbox email. Only meaningful with `--sandbox`. */
+    sandboxEmail?: string;
+    /** Skip MCP-client-config writes. Mostly for testing. */
+    noMcpConfig?: boolean;
+    /**
+     * Skip installing the `/amba-build` Claude Code skill into
+     * `.claude/skills/amba-build/SKILL.md`. Default behavior (when
+     * `--sandbox` is on) is to install the skill — pass `--no-skills`
+     * to opt out (e.g. in a CI run that doesn't want stray files).
+     */
+    noSkills?: boolean;
+    /** Emit a machine-readable JSON summary instead of human-readable lines. */
+    json?: boolean;
+    /** Override `~/` resolution. Test seam — production code never sets this. */
+    homeDir?: string;
 }
 export declare function initCommand(options?: InitOptions): Promise<void>;
+export declare function runSandboxInit(cwd: string, options: {
+    sandboxEmail?: string;
+    noMcpConfig?: boolean;
+    /**
+     * 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.
+     */
+    homeDir?: string;
+}): Promise<SandboxResult>;
+/**
+ * Build the plaintext (no ANSI) success-output block printed at the
+ * 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.
+ *
+ * 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.
+ *
+ * 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;