@layers/amba 4.0.3 → 4.0.4

package/dist/api-client.d.ts

@@ -277,6 +277,9 @@ export interface FunctionDeploymentRow {
     bundle_sha: string;
     status: 'active' | 'superseded' | 'disabled';
     created_at: string;
+    /** Opt-in public flag (#17). True = X-Api-Key gate skipped for this
+     *  function so external webhook senders can reach it. Default false. */
+    is_public?: boolean;
 }
 export declare function recordFunctionDeployment(projectId: string, input: {
     name: string;
@@ -310,6 +313,13 @@ export declare function deployFunctionViaApi(projectId: string, input: {
         max: number;
         key: 'user_id' | 'ip';
     } | null;
+    /**
+     * Opt-in public flag (#17). When true, the edge runtime skips the
+     * X-Api-Key gate for this function so third-party webhook senders can
+     * reach it. Default false (private). The customer verifies the webhook
+     * HMAC inside the handler.
+     */
+    public?: boolean;
 }): Promise<DeployFunctionResult>;
 export declare function listFunctionDeployments(projectId: string, options?: {
     activeOnly?: boolean;
@@ -379,6 +389,7 @@ export declare function getFunctionLogs(projectId: string, functionName: string,
     since?: string;
     until?: string;
     limit?: number;
+    requestId?: string;
 }): Promise<ApiResponse<FunctionLogsResponse>>;
 export interface QueueBinding {
     queue_name: string;
@@ -757,6 +768,27 @@ export declare function updateSiteDomain(projectId: string, siteName: string, ho
 export declare function detachSiteDomain(projectId: string, siteName: string, hostname: string): Promise<ApiResponse<{
     deleted: boolean;
 }>>;
+/** A declarative promotion bundle. Section keys are all optional. */
+export interface PromotionBundleWire {
+    version: number;
+    exported_at: string;
+    [section: string]: unknown;
+}
+/** `{ created, updated, skipped }` counts for one bundle section. */
+export interface PromotionSectionSummary {
+    created: number;
+    updated: number;
+    skipped: number;
+}
+export type PromotionImportMode = 'merge' | 'skip_existing';
+export interface PromotionImportResult {
+    mode: PromotionImportMode;
+    summary: Record<string, PromotionSectionSummary>;
+}
+/** GET the current project's declarative configuration bundle. */
+export declare function exportPromotionBundle(projectId: string): Promise<ApiResponse<PromotionBundleWire>>;
+/** POST a declarative bundle to import it into the project. */
+export declare function importPromotionBundle(projectId: string, bundle: PromotionBundleWire, mode: PromotionImportMode): Promise<ApiResponse<PromotionImportResult>>;
 export declare function validateApiKey(apiKey: string): Promise<{
     valid: false;
     error: string;

package/dist/bundle.d.ts

@@ -23,6 +23,25 @@
  * empty; customer code is expected to be self-contained.
  */
 import { type BuildOptions } from 'esbuild';
+/**
+ * Conventional entry-point filenames probed (in order) when
+ * `amba functions deploy <dir>` is pointed at a directory rather than a
+ * single file. Mirrors the Node / bundler convention (`index.*`) so a
+ * developer can `amba functions deploy ./my-fn` with an `index.ts` inside.
+ */
+export declare const FUNCTION_ENTRY_CANDIDATES: readonly string[];
+/**
+ * Resolve the bundler entry point from a deploy target that may be either a
+ * single file OR a directory.
+ *
+ *   - File  → returned as-is (single-file back-compat path).
+ *   - Dir   → resolved by convention to `index.{ts,js,mjs}`, or to an
+ *             explicit `entry` (relative to the directory) when provided.
+ *
+ * Throws an actionable error when the target doesn't exist, or when a
+ * directory has no resolvable entry point (and no `--entry` was passed).
+ */
+export declare function resolveFunctionEntry(target: string, explicitEntry?: string): Promise<string>;
 /**
  * Modules the bundler treats as `external` by default. The Amba
  * function runtime exposes zero npm packages — there is no "platform
@@ -46,6 +65,62 @@ export declare class BundleSizeError extends Error {
     readonly maxBytes: number;
     constructor(sizeBytes: number, maxBytes: number);
 }
+/**
+ * The single source-of-truth message for the wrong-handler-shape failure.
+ * Shared between the CLI bundler (pre-upload), the local `dev` runner, and
+ * the server-side deploy hint so dev / deploy / prod all describe the fix
+ * identically. Customer functions run as Module Workers; the legacy
+ * service-worker shape (`export default async function (req) { … }`) is
+ * rejected by the runtime at upload, so we reject it before the round-trip.
+ */
+export declare const HANDLER_SHAPE_FIX_MESSAGE: string;
+/** Message used when the entry file has no `export default` at all. */
+export declare const HANDLER_SHAPE_MISSING_DEFAULT_MESSAGE: string;
+/** Message used when the default export is present but has no `fetch` method. */
+export declare const HANDLER_SHAPE_NO_FETCH_MESSAGE: string;
+/**
+ * Thrown when the bundled entry's `export default` is not the Module Worker
+ * shape (`{ fetch(req, env, ctx) }`). Raised BEFORE any upload so a wrong
+ * handler shape fails fast on the developer's machine with an actionable
+ * message instead of an opaque upstream rejection at deploy time.
+ */
+export declare class HandlerShapeError extends Error {
+    readonly kind: 'plain-function' | 'missing-default' | 'no-fetch';
+    constructor(message: string, kind: 'plain-function' | 'missing-default' | 'no-fetch');
+}
+/**
+ * Inspect an already-imported module namespace and assert it has the
+ * Module Worker handler shape: a default export that is an object (or
+ * function-with-properties) carrying a callable `fetch`.
+ *
+ * Pure + side-effect free — it only reads the shape of `mod.default`, never
+ * invokes `fetch`. This is the unit-testable core; `assertModuleWorkerShape`
+ * wraps the import-from-code plumbing around it.
+ *
+ * Throws `HandlerShapeError` on:
+ *   - no default export (`missing-default`)
+ *   - a default-exported plain function — the legacy service-worker shape
+ *     (`plain-function`)
+ *   - a default export with no callable `fetch` (`no-fetch`)
+ */
+export declare function assertHandlerShape(mod: {
+    default?: unknown;
+}): void;
+/**
+ * Validate that the bundled customer code exports the Module Worker handler
+ * shape, by importing it in isolation and inspecting `mod.default`.
+ *
+ * Mechanism: write the bundle to a throwaway temp `.mjs` and dynamic-import
+ * it, then hand the namespace to `assertHandlerShape`. This is the same
+ * import-and-inspect approach the local `dev` runner uses
+ * (`functions.ts` DEV_RUNNER_SOURCE) — reused here so the pre-upload check
+ * and the dev runner agree on what "valid shape" means. Importing runs the
+ * module's top-level code (unavoidable to read the export), but the handler
+ * itself is NEVER invoked — we only read the shape of the exported object.
+ *
+ * The temp file is always cleaned up (best-effort) before returning.
+ */
+export declare function assertModuleWorkerShape(code: string): Promise<void>;
 export interface BundleResult {
     /** The bundled JS source (UTF-8). */
     code: string;
@@ -67,6 +142,17 @@ export interface BundleOptions {
     extraExternals?: string[];
     /** Source map handling. Default: inline. */
     sourcemap?: BuildOptions['sourcemap'];
+    /**
+     * Validate the bundled entry exports the Module Worker handler shape
+     * (`export default { async fetch(req, env, ctx) { … } }`) before
+     * returning, throwing `HandlerShapeError` if not. Default: true.
+     *
+     * The check imports the bundle in isolation to inspect `mod.default`;
+     * it never invokes the handler. Both `deploy` and `dev` leave this on so
+     * a function that bundles in `dev` cannot fail the shape check in
+     * `deploy` (dev / prod parity).
+     */
+    validateHandlerShape?: boolean;
 }
 /**
  * Bundle a customer function file for upload to a Workers dispatch

package/dist/commands/functions-logs.d.ts

@@ -26,5 +26,7 @@ export interface FunctionsLogsOptions {
     tail?: boolean;
     /** NDJSON output. */
     json?: boolean;
+    /** Only show events whose log/exception text mentions this request id (`r_...`). */
+    requestId?: string;
 }
 export declare function functionsLogsCommand(functionName: string, options?: FunctionsLogsOptions): Promise<void>;

package/dist/commands/functions.d.ts

@@ -9,8 +9,19 @@
  */
 import { type RateLimitConfig } from '../_internal/shared.js';
 export interface DeployOptions {
-    /** Override the function name. Default: filename without extension. */
+    /**
+     * Override the function name. Default: when a file is deployed, the
+     * filename without extension; when a directory is deployed, the
+     * directory's leaf name (NOT the resolved `index` entry's name).
+     */
     name?: string;
+    /**
+     * Entry file when the deploy target is a DIRECTORY (relative to it).
+     * Only valid with a directory target; ignored for single-file deploys.
+     * When omitted, a directory resolves its entry by convention
+     * (`index.ts` / `index.js` / `index.mjs`).
+     */
+    entry?: string;
     /** Print bundle report but skip the CF API + DB write. Useful for size triage. */
     dryRun?: boolean;
     /**
@@ -23,8 +34,16 @@ export interface DeployOptions {
     rateLimitWindow?: string;
     rateLimitMax?: number;
     rateLimitKey?: string;
+    /**
+     * Opt-in public flag (#17). Deploy the function WITHOUT the X-Api-Key
+     * gate so third-party webhook senders (Stripe, RevenueCat, GitHub,
+     * Slack) that can't attach a custom header can reach it. Default false
+     * (private). The customer MUST verify the webhook HMAC signature inside
+     * the handler — public skips the credential gate only.
+     */
+    public?: boolean;
 }
-export declare function functionsDeployCommand(entryPoint: string, options?: DeployOptions): Promise<void>;
+export declare function functionsDeployCommand(target: string, options?: DeployOptions): Promise<void>;
 export declare function functionsListCommand(): Promise<void>;
 export declare function functionsDeleteCommand(name: string, options?: {
     confirm?: string;

package/dist/commands/iac.d.ts

@@ -0,0 +1,116 @@
+/**
+ * `amba apply` / `amba diff` / `amba export` — declarative
+ * infrastructure-as-code for a project's reusable configuration.
+ *
+ * A declarative bundle (default `amba.config.json`) captures the entities a
+ * developer hand-builds once and wants to stand up identically elsewhere:
+ * remote configs, collection schemas, content libraries + items, currencies,
+ * achievements, streaks, challenges, leaderboards, and xp_rules. It carries
+ * CONFIGURATION ONLY — no secrets, no per-user data.
+ *
+ * These commands wrap the platform's promotion endpoints:
+ *   GET  /v1/admin/projects/:p/promotion/export
+ *   POST /v1/admin/projects/:p/promotion/import   (mode=skip_existing|merge)
+ *
+ *   - `amba export [file]`  writes the current project's bundle to disk.
+ *   - `amba apply  [file]`  POSTs the local bundle to the import endpoint and
+ *                           prints a `{ created, updated, skipped }` summary
+ *                           per section (the server's authoritative result).
+ *   - `amba diff   [file]`  shows what `apply` WOULD change without writing.
+ *                           The import route has NO server-side dry-run, so
+ *                           `diff` exports the current project and computes the
+ *                           created/updated/skipped per section LOCALLY.
+ */
+import { type PromotionBundleWire, type PromotionImportMode } from '../api-client.js';
+/** Default declarative bundle filename when no `[file]` is passed. */
+export declare const DEFAULT_BUNDLE_FILE = "amba.config.json";
+export interface ApplyOptions {
+    project?: string;
+    /** `skip_existing` (default) no-ops on conflict; `merge` refreshes. */
+    mode?: PromotionImportMode;
+}
+export interface DiffOptions {
+    project?: string;
+    mode?: PromotionImportMode;
+}
+export interface ExportOptions {
+    project?: string;
+}
+/** Per-section, per-key diff outcome. */
+export interface SectionDiff {
+    created: number;
+    updated: number;
+    skipped: number;
+}
+export type LocalDiff = Record<string, SectionDiff>;
+/**
+ * Read + parse a declarative bundle from disk. JSON only — we deliberately
+ * don't pull in a YAML dependency the CLI doesn't already ship (the package
+ * has no YAML lib), so `.yaml`/`.yml` files are rejected with a clear hint
+ * rather than silently mis-parsed.
+ */
+export declare function readBundleFile(file: string): Promise<PromotionBundleWire>;
+/**
+ * Pure section-by-section diff of a desired bundle against the current
+ * project's exported bundle. The classification MIRRORS the server's import
+ * (`apps/api/src/lib/promotion-bundle.ts`) so `amba diff` agrees with what
+ * `amba apply` will report:
+ *   - created — natural key absent in current.
+ *   - updated — natural key present AND `mode === 'merge'`. The server runs an
+ *               UNCONDITIONAL update for every existing key in merge mode and
+ *               increments `updated` — it does NOT compare field values, so we
+ *               don't either (a local field comparison made `diff` under-report).
+ *   - skipped — natural key present under `skip_existing`; OR an existing
+ *               collection (always — collections are create-if-absent, never
+ *               merged); OR a `remote_configs` row flagged `is_system: true`
+ *               (the server always skips those before any existence check); OR
+ *               a desired row with no valid natural key (can't be matched
+ *               against the export, and the server import dedups by that key —
+ *               so it is never a reliable create).
+ *
+ * Within one bundle section, the server walks rows sequentially and each
+ * insert mutates the DB, so a SECOND row sharing a natural key already created
+ * by an EARLIER row in the same section is seen as existing (→ skip under
+ * skip_existing, update under merge) rather than created a second time. We
+ * track already-seen keys per section to mirror that, so duplicate-keyed local
+ * rows don't inflate the `created` total versus what `apply` does.
+ */
+export declare function computeLocalDiff(desired: PromotionBundleWire, current: PromotionBundleWire, mode: PromotionImportMode): LocalDiff;
+declare function totalOf(s: {
+    created: number;
+    updated: number;
+    skipped: number;
+}): number;
+/** Roll a per-section diff up into grand totals across every section. */
+export declare function summarizeDiff(diff: Record<string, SectionDiff>): SectionDiff;
+/**
+ * `amba export [file]` — write the current project's declarative bundle to
+ * disk so it can be checked in, diffed, and re-applied.
+ */
+export declare function exportConfigCommand(file?: string, options?: ExportOptions): Promise<void>;
+/**
+ * `amba apply [file]` — read a local declarative bundle and POST it to the
+ * import endpoint. Prints the server's authoritative `{ created, updated,
+ * skipped }` per section.
+ */
+export declare function applyConfigCommand(file?: string, options?: ApplyOptions): Promise<void>;
+/**
+ * `amba diff [file]` — show what `apply` WOULD change without writing.
+ *
+ * The import route has no server-side dry-run, so this fetches the current
+ * project's exported bundle and computes the diff LOCALLY. Output mirrors the
+ * `apply` summary shape so the two read identically.
+ */
+export declare function diffConfigCommand(file?: string, options?: DiffOptions): Promise<void>;
+/** Test-only re-export of internal helpers. Not a public API. */
+export declare const __testHelpers: {
+    computeLocalDiff: typeof computeLocalDiff;
+    summarizeDiff: typeof summarizeDiff;
+    readBundleFile: typeof readBundleFile;
+    BUNDLE_SECTIONS: readonly {
+        key: string;
+        naturalKey: string;
+    }[];
+    totalOf: typeof totalOf;
+};
+export {};

package/dist/commands/monetization.d.ts

@@ -0,0 +1,36 @@
+/**
+ * `amba monetization *` subcommands — CLI access to the monetization control
+ * plane behind `/v1/admin/projects/:id/monetization/*`.
+ *
+ *   amba monetization plan     — three-way diff (declared vs adopted baseline
+ *                                vs live provider) + store-floor preflight +
+ *                                drift. READ-ONLY — previews; applies nothing.
+ *   amba monetization drift    — out-of-band changes to Amba-managed objects.
+ *   amba monetization export   — snapshot the live config to a declarative
+ *                                bundle (the `monetization` section), to stdout
+ *                                or a file.
+ *   amba monetization adopt    — record the live config as the managed baseline
+ *                                so the next plan is a no-op. Writes ONLY Amba's
+ *                                own state — never the provider. Idempotent.
+ *   amba monetization apply    — push the declared config to the provider.
+ *                                ADDITIVE only: create entitlements/offerings/
+ *                                packages/paywall-drafts + attach products.
+ *                                Refuses if the provider drifted since the plan;
+ *                                never does destructive changes.
+ *
+ * Project is resolved via `loadProjectConfig` — same pattern as the other
+ * project-scoped CLI commands.
+ */
+export declare function monetizationPlanCommand(): Promise<void>;
+export declare function monetizationDriftCommand(): Promise<void>;
+export declare function monetizationExportCommand(options?: {
+    file?: string;
+}): Promise<void>;
+export declare function monetizationAdoptCommand(options?: {
+    all?: boolean;
+}): Promise<void>;
+export declare function monetizationApplyCommand(options?: {
+    confirm?: boolean;
+    allowDetachLive?: boolean;
+    reconcile?: string;
+}): Promise<void>;

package/dist/commands/payments.d.ts

@@ -0,0 +1,33 @@
+/**
+ * `amba payments *` subcommands — CLI access to the Amba Payments (Stripe
+ * Connect platform) surface at `/v1/admin/projects/:id/payments/*`
+ * (tracker #10).
+ *
+ * Amba is the payments rail for the developer's app: the app is the seller,
+ * Amba takes a platform fee, Stripe carries money-transmission. This is the
+ * developer-facing onboarding + config + reporting surface, so naming Stripe
+ * here is by intent (same as `amba billing`).
+ *
+ *   amba payments setup                    — create the connected account +
+ *                                            print the hosted onboarding URL.
+ *   amba payments status                   — onboarding stage + capability flags.
+ *   amba payments set-fee <bps|off>        — default platform fee (basis points).
+ *   amba payments balance                  — connected-account balance.
+ *   amba payments payouts                  — recent payouts.
+ *
+ * Every live call is gated by the platform's PAYMENTS_CONNECT_LIVE
+ * kill-switch — when off the API returns PAYMENTS_NOT_ENABLED, surfaced
+ * verbatim here. Project resolved via loadProjectConfig (same as billing).
+ */
+export declare function paymentsSetupCommand(input: {
+    country?: string;
+    email?: string;
+}): Promise<void>;
+export declare function paymentsStatusCommand(): Promise<void>;
+export declare function paymentsSetFeeCommand(input: {
+    bps: number | null;
+}): Promise<void>;
+export declare function paymentsBalanceCommand(): Promise<void>;
+export declare function paymentsPayoutsCommand(input: {
+    limit?: number;
+}): Promise<void>;