@layers/amba 1.1.0 → 4.0.3

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>;