@oxy-hq/sdk 2.12.0 → 2.16.0

package/dist/{react-DW7Z96sD.d.mts → react-CljeXJuw.d.cts}

@@ -23,8 +23,40 @@ interface OxyAppFunctionManifest {
     pipeline: string;
     resource: string;
   };
+  /**
+   * Receive an unauthenticated POST from a third party at
+   * `POST /api/webhooks/apps/<org>/<app>/<name>`.
+   *
+   * The PLATFORM verifies every request — HMAC-SHA256 over the raw body, in
+   * constant time — before the function is enqueued, so app code never sees an
+   * unverified request. Omit the block and that endpoint answers 404, as if it
+   * did not exist.
+   */
+  webhook?: {
+    /**
+     * App-secret key holding the signing key(s) — the same `apps/<app-id>/`
+     * namespace `ctx.env` reads. The manifest names the secret, never holds it.
+     *
+     * **Comma-separated for rotation.** Providers that keep two live signing
+     * keys (Uber's `BASIC_HMAC` does) sign with either during a rotation; any
+     * match passes, so adopting a new key does not drop the events still
+     * signed with the old one.
+     */
+    secretVar: string;
+    /** Header carrying the signature, e.g. `x-uber-signature`. */
+    signatureHeader: string;
+    /** How the digest is encoded. Default `hex`. */
+    encoding?: "hex" | "base64";
+  };
   /** Wall-clock timeout. Default 30, max 300. */
   timeoutSeconds?: number;
+  /**
+   * Mark this function as a check. `oxyc checks run` runs it; with a
+   * `schedule` the platform runs it continuously and a failure pages. A
+   * check fails when it throws, times out, or returns `{ ok: false }`.
+   * Checks must not have customer-visible side effects.
+   */
+  check?: boolean;
   /**
    * Opt-in result caching for route invocations. Omit (the default) to never
    * cache — the safe choice for a side-effectful function (writes, external
@@ -43,13 +75,31 @@ interface OxyAppFunctionManifest {
    * destination here ONLY for a function that legitimately writes to it; a
    * read-only function omits it. This scopes writes away from the project's
    * source warehouse.
+   *
+   * A customer warehouse (anything but `airhouse` / `airhouse_managed`) is
+   * read-only: listing it here is not enough, it must also appear in
+   * `customerWarehouseWrites` with a reason.
    */
   destinations?: string[];
+  /**
+   * Customer warehouses this function writes to anyway, each with the reason —
+   * the exception to "customer warehouses are read-only". Every key must also be
+   * in `destinations`; a write to a customer warehouse not named here is refused.
+   * Prefer moving the data: facts to `airhouse`, records to `oltp`.
+   *
+   * ```json
+   * "customerWarehouseWrites": {
+   *   "clickhouse": "Journal entries stay beside the legacy ClickHouse facts until QuickBooks lands in Airhouse"
+   * }
+   * ```
+   */
+  customerWarehouseWrites?: Record<string, string>;
   /**
    * Capability to write app-scoped secrets via `ctx.secrets.set` (fail-closed:
    * omit → writes rejected). Only the app's own `apps/<app-id>/` namespace is
-   * writable. Declare for a function that persists state — e.g. a scheduled
-   * token-refresher that writes the rotated token back to Oxy Secrets.
+   * writable. Declare for a function that rotates a credential — e.g. a
+   * scheduled token-refresher that writes the rotated token back to Oxy Secrets.
+   * Secrets are not a state store: a cursor or counter is a record for `oltp`.
    */
   secrets?: {
     write?: boolean;
@@ -102,6 +152,17 @@ interface OxyAppFunctionManifest {
   oltp?: {
     enabled?: boolean;
   };
+  /**
+   * Capability for `ctx.airhouse` — append the app's own FACTS (what happened,
+   * never edited) to its schema in the workspace's Airhouse (fail-closed: omit →
+   * every `ctx.airhouse` call rejected). A pure GATE like `oltp`: the schema is
+   * derived from the app's slug (`store-ops` → `app_store_ops`), never named
+   * here. Writes run as the app, whoever invoked the function, so a scheduled
+   * run can write. Tables come from `airhouseMigrations`.
+   */
+  airhouse?: {
+    enabled?: boolean;
+  };
   /**
    * Retry policy for **background** runs (a `schedule` fire or a manual job
    * trigger). Omit → a job run is attempted once. Route (HTTP) invocations are
@@ -128,9 +189,9 @@ interface OxyAppManifest {
   /** Must be 2. v1 manifests are no longer supported. */
   schemaVersion: 2;
   /**
-   * Optional display name. The admin "Link existing" dialog prefills
-   * its Name field from this. Omit to let oxy fall back to the
-   * folder basename.
+   * Optional display name. Informational: the name an app shows is its
+   * registry row's, set when the row is created (the admin **New app**
+   * dialog, or `oxyc publish --name` on a first publish).
    */
   name?: string;
   /**
@@ -159,7 +220,8 @@ interface OxyAppManifest {
    */
   functions?: Record<string, OxyAppFunctionManifest>;
   /**
-   * Schema migrations that ship WITH this bundle and run on promote.
+   * Schema migrations for the app's OLTP store (`ctx.oltp`) that ship WITH this
+   * bundle and run on promote.
    *
    * `dir` is a directory inside the built bundle holding numbered `.sql` files.
    * The platform runs them in lexical order, **once each, ever**, inside a
@@ -177,6 +239,18 @@ interface OxyAppManifest {
   migrations?: {
     dir: string;
   };
+  /**
+   * Tables for the app's FACTS, in its Airhouse schema `app_<writer>`: a
+   * directory of numbered `.sql` files run once each, at promote, with the same
+   * ledger rules as `migrations` (never edit, rename or copy one that ran).
+   *
+   * Every object must be named `app_<writer>.<name>`. Airhouse is DuckLake, so a
+   * file declaring a PRIMARY KEY, UNIQUE, an index or a foreign key is refused at
+   * publish — a table carrying one fails and leaves the writer inert.
+   */
+  airhouseMigrations?: {
+    dir: string;
+  };
   /**
    * Optional Ask Oxygen binding (agent ref + composer chips). The
    * platform's registered copy is authoritative (surfaced by
@@ -187,6 +261,37 @@ interface OxyAppManifest {
     agent?: string;
     suggestedQuestions?: string[];
   };
+  /**
+   * The secrets this app expects, keyed by env-var name — the app's
+   * `.env.example`, declared rather than written in a README.
+   *
+   * These are the keys your functions read as `ctx.env.KEY`. Declaring one puts
+   * it in the app's Secrets surface (staff console → app → Secrets, and the
+   * workspace's own settings) as a row to fill in, so a fresh deploy says what
+   * is still missing instead of failing at the first invocation. Every function's
+   * `webhook.secretVar` is folded in automatically — no need to repeat it here.
+   *
+   * **Names only, never values.** A manifest ships inside the bundle and is
+   * fetchable over the app's own host; putting a secret in one publishes it.
+   * Values are set out-of-band on the Secrets surface, or by
+   * `ctx.secrets.set` from a function holding the `secrets.write` capability.
+   *
+   * App-level rather than per-function, because a secret is app-scoped by
+   * construction: two functions sharing `STRIPE_API_KEY` read the same value,
+   * so it can only be described once.
+   *
+   * ```jsonc
+   * "env": {
+   *   "STRIPE_API_KEY":    { "required": true, "description": "Restricted key, Dashboard → Developers" },
+   *   "SLACK_WEBHOOK_URL": { "description": "Optional ops channel" }
+   * }
+   * ```
+   *
+   * Read by the platform at **publish time** (like {@link OxyAppStorageManifest}),
+   * so the block is documented here but not round-tripped through the dev-time
+   * manifest fetch.
+   */
+  env?: Record<string, OxyAppEnvDeclaration>;
   /**
    * Optional app-level storage policy. Distinct from the per-function
    * `storage: { read, write }` capability: those gate what one function may
@@ -220,6 +325,24 @@ interface OxyAppManifest {
    */
   analytics?: boolean;
 }
+/** One declared secret — an entry in the `env` block of `oxy-app.json`. */
+interface OxyAppEnvDeclaration {
+  /**
+   * Flag the key as **Missing** (rather than merely absent) while nothing is
+   * stored for it, and count it in the app's missing-secrets badge.
+   *
+   * Advisory, not a gate: a publish is never blocked on an unset key, because
+   * the first publish is exactly when nobody could have set one yet.
+   *
+   * Default: `false` — a declaration is documentation first.
+   */
+  required?: boolean;
+  /**
+   * Shown beside the key on the Secrets surface. Say what it is and where to
+   * get one — this is the text that saves someone a Slack message.
+   */
+  description?: string;
+}
 /** Browser-runtime performance opt-outs — the `performance` block in `oxy-app.json`. */
 interface OxyAppPerformanceManifest {
   /**
@@ -387,6 +510,14 @@ type FunctionError = Error & {
   logs?: FunctionLog[];
   status?: number;
   body?: unknown;
+  /**
+   * The platform trace this invoke ran in (32 hex chars) and the server-minted
+   * `x-oxy-request-id`, when the request got as far as the server. Quote
+   * either in a bug report: an operator can open the trace in HyperDX, and
+   * an app admin can filter the app's Logs by the request.
+   */
+  traceId?: string;
+  requestId?: string;
 };
 //#endregion
 //#region src/custom-app/react.d.ts
@@ -509,7 +640,10 @@ interface UseFunctionResult<Data = unknown> {
   data: Data | null;
   /** True while an invocation is in flight. */
   isLoading: boolean;
-  /** Last invocation error, or null. On error this carries `.logs` too. */
+  /**
+   * Last invocation error, or null. On error this carries `.logs`, and
+   * `.traceId` / `.requestId` — the ids that name the run to an operator.
+   */
   error: Error | null;
   /**
    * `console.*` / `ctx.log` output from the last invoke (success or error), so
@@ -836,4 +970,4 @@ interface OxyChatProps {
 declare function OxyChat(props: OxyChatProps): React.JSX.Element;
 //#endregion
 export { loadCustomAppManifest as $, UseSemanticQueryOpts as A, FunctionError as B, UseProcedureRunInput as C, UseQueryOpts as D, UseQueryInput as E, useProcedureRun as F, apiErrorFromResponse as G, FunctionResult as H, useQuery as I, OxyAppFunctionManifest as J, interpretCustomAppError as K, useResolvedManifest as L, useAgentRun as M, useFunction as N, UseQueryResult as O, useOxyApp as P, _resetCustomAppManifestCacheForTest as Q, useSemanticQuery as R, UseFunctionResult as S, UseProcedureRunResult as T, CustomAppErrorReport as U, FunctionLog as V, OxyApiError as W, OxyAppPerformanceManifest as X, OxyAppManifest as Y, ResolvedCustomAppManifest as Z, SemanticFilter as _, AppFetcher as a, UseAgentRunInput as b, OxyAppProvider as c, OxyChatProps as d, ProcedureProgress as f, SemanticDateRangeOp as g, SemanticArrayOp as h, AgentSqlArtifact as i, UseSemanticQueryResult as j, UseSemanticQueryInput as k, OxyAppProviderProps as l, ProcedureRunState as m, AgentRunEvent as n, OxyAnswer as o, ProcedureResult as p, LoadManifestOptions as q, AgentRunState as r, OxyAnswerProps as s, AgentArtifact as t, OxyChat as u, SemanticScalarOp as v, UseProcedureRunOpts as w, UseAgentRunResult as x, SemanticTimeDimension as y, useTrackEvent as z };
-//# sourceMappingURL=react-DW7Z96sD.d.mts.map
+//# sourceMappingURL=react-CljeXJuw.d.cts.map

package/dist/react-CljeXJuw.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-CljeXJuw.d.cts","names":[],"sources":["../src/custom-app/manifest.ts","../src/custom-app/errors.ts","../src/custom-app/function-sse.ts","../src/custom-app/react.tsx"],"mappings":"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"}

package/dist/{react-DW7Z96sD.d.cts → react-CljeXJuw.d.mts}

@@ -23,8 +23,40 @@ interface OxyAppFunctionManifest {
     pipeline: string;
     resource: string;
   };
+  /**
+   * Receive an unauthenticated POST from a third party at
+   * `POST /api/webhooks/apps/<org>/<app>/<name>`.
+   *
+   * The PLATFORM verifies every request — HMAC-SHA256 over the raw body, in
+   * constant time — before the function is enqueued, so app code never sees an
+   * unverified request. Omit the block and that endpoint answers 404, as if it
+   * did not exist.
+   */
+  webhook?: {
+    /**
+     * App-secret key holding the signing key(s) — the same `apps/<app-id>/`
+     * namespace `ctx.env` reads. The manifest names the secret, never holds it.
+     *
+     * **Comma-separated for rotation.** Providers that keep two live signing
+     * keys (Uber's `BASIC_HMAC` does) sign with either during a rotation; any
+     * match passes, so adopting a new key does not drop the events still
+     * signed with the old one.
+     */
+    secretVar: string;
+    /** Header carrying the signature, e.g. `x-uber-signature`. */
+    signatureHeader: string;
+    /** How the digest is encoded. Default `hex`. */
+    encoding?: "hex" | "base64";
+  };
   /** Wall-clock timeout. Default 30, max 300. */
   timeoutSeconds?: number;
+  /**
+   * Mark this function as a check. `oxyc checks run` runs it; with a
+   * `schedule` the platform runs it continuously and a failure pages. A
+   * check fails when it throws, times out, or returns `{ ok: false }`.
+   * Checks must not have customer-visible side effects.
+   */
+  check?: boolean;
   /**
    * Opt-in result caching for route invocations. Omit (the default) to never
    * cache — the safe choice for a side-effectful function (writes, external
@@ -43,13 +75,31 @@ interface OxyAppFunctionManifest {
    * destination here ONLY for a function that legitimately writes to it; a
    * read-only function omits it. This scopes writes away from the project's
    * source warehouse.
+   *
+   * A customer warehouse (anything but `airhouse` / `airhouse_managed`) is
+   * read-only: listing it here is not enough, it must also appear in
+   * `customerWarehouseWrites` with a reason.
    */
   destinations?: string[];
+  /**
+   * Customer warehouses this function writes to anyway, each with the reason —
+   * the exception to "customer warehouses are read-only". Every key must also be
+   * in `destinations`; a write to a customer warehouse not named here is refused.
+   * Prefer moving the data: facts to `airhouse`, records to `oltp`.
+   *
+   * ```json
+   * "customerWarehouseWrites": {
+   *   "clickhouse": "Journal entries stay beside the legacy ClickHouse facts until QuickBooks lands in Airhouse"
+   * }
+   * ```
+   */
+  customerWarehouseWrites?: Record<string, string>;
   /**
    * Capability to write app-scoped secrets via `ctx.secrets.set` (fail-closed:
    * omit → writes rejected). Only the app's own `apps/<app-id>/` namespace is
-   * writable. Declare for a function that persists state — e.g. a scheduled
-   * token-refresher that writes the rotated token back to Oxy Secrets.
+   * writable. Declare for a function that rotates a credential — e.g. a
+   * scheduled token-refresher that writes the rotated token back to Oxy Secrets.
+   * Secrets are not a state store: a cursor or counter is a record for `oltp`.
    */
   secrets?: {
     write?: boolean;
@@ -102,6 +152,17 @@ interface OxyAppFunctionManifest {
   oltp?: {
     enabled?: boolean;
   };
+  /**
+   * Capability for `ctx.airhouse` — append the app's own FACTS (what happened,
+   * never edited) to its schema in the workspace's Airhouse (fail-closed: omit →
+   * every `ctx.airhouse` call rejected). A pure GATE like `oltp`: the schema is
+   * derived from the app's slug (`store-ops` → `app_store_ops`), never named
+   * here. Writes run as the app, whoever invoked the function, so a scheduled
+   * run can write. Tables come from `airhouseMigrations`.
+   */
+  airhouse?: {
+    enabled?: boolean;
+  };
   /**
    * Retry policy for **background** runs (a `schedule` fire or a manual job
    * trigger). Omit → a job run is attempted once. Route (HTTP) invocations are
@@ -128,9 +189,9 @@ interface OxyAppManifest {
   /** Must be 2. v1 manifests are no longer supported. */
   schemaVersion: 2;
   /**
-   * Optional display name. The admin "Link existing" dialog prefills
-   * its Name field from this. Omit to let oxy fall back to the
-   * folder basename.
+   * Optional display name. Informational: the name an app shows is its
+   * registry row's, set when the row is created (the admin **New app**
+   * dialog, or `oxyc publish --name` on a first publish).
    */
   name?: string;
   /**
@@ -159,7 +220,8 @@ interface OxyAppManifest {
    */
   functions?: Record<string, OxyAppFunctionManifest>;
   /**
-   * Schema migrations that ship WITH this bundle and run on promote.
+   * Schema migrations for the app's OLTP store (`ctx.oltp`) that ship WITH this
+   * bundle and run on promote.
    *
    * `dir` is a directory inside the built bundle holding numbered `.sql` files.
    * The platform runs them in lexical order, **once each, ever**, inside a
@@ -177,6 +239,18 @@ interface OxyAppManifest {
   migrations?: {
     dir: string;
   };
+  /**
+   * Tables for the app's FACTS, in its Airhouse schema `app_<writer>`: a
+   * directory of numbered `.sql` files run once each, at promote, with the same
+   * ledger rules as `migrations` (never edit, rename or copy one that ran).
+   *
+   * Every object must be named `app_<writer>.<name>`. Airhouse is DuckLake, so a
+   * file declaring a PRIMARY KEY, UNIQUE, an index or a foreign key is refused at
+   * publish — a table carrying one fails and leaves the writer inert.
+   */
+  airhouseMigrations?: {
+    dir: string;
+  };
   /**
    * Optional Ask Oxygen binding (agent ref + composer chips). The
    * platform's registered copy is authoritative (surfaced by
@@ -187,6 +261,37 @@ interface OxyAppManifest {
     agent?: string;
     suggestedQuestions?: string[];
   };
+  /**
+   * The secrets this app expects, keyed by env-var name — the app's
+   * `.env.example`, declared rather than written in a README.
+   *
+   * These are the keys your functions read as `ctx.env.KEY`. Declaring one puts
+   * it in the app's Secrets surface (staff console → app → Secrets, and the
+   * workspace's own settings) as a row to fill in, so a fresh deploy says what
+   * is still missing instead of failing at the first invocation. Every function's
+   * `webhook.secretVar` is folded in automatically — no need to repeat it here.
+   *
+   * **Names only, never values.** A manifest ships inside the bundle and is
+   * fetchable over the app's own host; putting a secret in one publishes it.
+   * Values are set out-of-band on the Secrets surface, or by
+   * `ctx.secrets.set` from a function holding the `secrets.write` capability.
+   *
+   * App-level rather than per-function, because a secret is app-scoped by
+   * construction: two functions sharing `STRIPE_API_KEY` read the same value,
+   * so it can only be described once.
+   *
+   * ```jsonc
+   * "env": {
+   *   "STRIPE_API_KEY":    { "required": true, "description": "Restricted key, Dashboard → Developers" },
+   *   "SLACK_WEBHOOK_URL": { "description": "Optional ops channel" }
+   * }
+   * ```
+   *
+   * Read by the platform at **publish time** (like {@link OxyAppStorageManifest}),
+   * so the block is documented here but not round-tripped through the dev-time
+   * manifest fetch.
+   */
+  env?: Record<string, OxyAppEnvDeclaration>;
   /**
    * Optional app-level storage policy. Distinct from the per-function
    * `storage: { read, write }` capability: those gate what one function may
@@ -220,6 +325,24 @@ interface OxyAppManifest {
    */
   analytics?: boolean;
 }
+/** One declared secret — an entry in the `env` block of `oxy-app.json`. */
+interface OxyAppEnvDeclaration {
+  /**
+   * Flag the key as **Missing** (rather than merely absent) while nothing is
+   * stored for it, and count it in the app's missing-secrets badge.
+   *
+   * Advisory, not a gate: a publish is never blocked on an unset key, because
+   * the first publish is exactly when nobody could have set one yet.
+   *
+   * Default: `false` — a declaration is documentation first.
+   */
+  required?: boolean;
+  /**
+   * Shown beside the key on the Secrets surface. Say what it is and where to
+   * get one — this is the text that saves someone a Slack message.
+   */
+  description?: string;
+}
 /** Browser-runtime performance opt-outs — the `performance` block in `oxy-app.json`. */
 interface OxyAppPerformanceManifest {
   /**
@@ -387,6 +510,14 @@ type FunctionError = Error & {
   logs?: FunctionLog[];
   status?: number;
   body?: unknown;
+  /**
+   * The platform trace this invoke ran in (32 hex chars) and the server-minted
+   * `x-oxy-request-id`, when the request got as far as the server. Quote
+   * either in a bug report: an operator can open the trace in HyperDX, and
+   * an app admin can filter the app's Logs by the request.
+   */
+  traceId?: string;
+  requestId?: string;
 };
 //#endregion
 //#region src/custom-app/react.d.ts
@@ -509,7 +640,10 @@ interface UseFunctionResult<Data = unknown> {
   data: Data | null;
   /** True while an invocation is in flight. */
   isLoading: boolean;
-  /** Last invocation error, or null. On error this carries `.logs` too. */
+  /**
+   * Last invocation error, or null. On error this carries `.logs`, and
+   * `.traceId` / `.requestId` — the ids that name the run to an operator.
+   */
   error: Error | null;
   /**
    * `console.*` / `ctx.log` output from the last invoke (success or error), so
@@ -836,4 +970,4 @@ interface OxyChatProps {
 declare function OxyChat(props: OxyChatProps): React.JSX.Element;
 //#endregion
 export { loadCustomAppManifest as $, UseSemanticQueryOpts as A, FunctionError as B, UseProcedureRunInput as C, UseQueryOpts as D, UseQueryInput as E, useProcedureRun as F, apiErrorFromResponse as G, FunctionResult as H, useQuery as I, OxyAppFunctionManifest as J, interpretCustomAppError as K, useResolvedManifest as L, useAgentRun as M, useFunction as N, UseQueryResult as O, useOxyApp as P, _resetCustomAppManifestCacheForTest as Q, useSemanticQuery as R, UseFunctionResult as S, UseProcedureRunResult as T, CustomAppErrorReport as U, FunctionLog as V, OxyApiError as W, OxyAppPerformanceManifest as X, OxyAppManifest as Y, ResolvedCustomAppManifest as Z, SemanticFilter as _, AppFetcher as a, UseAgentRunInput as b, OxyAppProvider as c, OxyChatProps as d, ProcedureProgress as f, SemanticDateRangeOp as g, SemanticArrayOp as h, AgentSqlArtifact as i, UseSemanticQueryResult as j, UseSemanticQueryInput as k, OxyAppProviderProps as l, ProcedureRunState as m, AgentRunEvent as n, OxyAnswer as o, ProcedureResult as p, LoadManifestOptions as q, AgentRunState as r, OxyAnswerProps as s, AgentArtifact as t, OxyChat as u, SemanticScalarOp as v, UseProcedureRunOpts as w, UseAgentRunResult as x, SemanticTimeDimension as y, useTrackEvent as z };
-//# sourceMappingURL=react-DW7Z96sD.d.cts.map
+//# sourceMappingURL=react-CljeXJuw.d.mts.map

package/dist/react-CljeXJuw.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"react-CljeXJuw.d.mts","names":[],"sources":["../src/custom-app/manifest.ts","../src/custom-app/errors.ts","../src/custom-app/function-sse.ts","../src/custom-app/react.tsx"],"mappings":"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"}