primitive-functions 0.2.0-alpha.6 → 0.2.0-alpha.8

package/index.d.ts

@@ -74,7 +74,16 @@ export type FunctionTrigger =
    * parent was a request invocation over HTTP, which writes no run row, or a
    * database-change fire, which writes none either.
    */
-  | { kind: "function"; functionKey: string; runId: string | null };
+  | { kind: "function"; functionKey: string; runId: string | null }
+  /**
+   * An admin ran this function as the SYSTEM, from outside any trigger
+   * (#3448) — `primitive functions invoke --as system`.
+   *
+   * `ctx.user` is null and the code runs with the app's system authority, as
+   * it does for a cron or webhook fire. `userId` names the admin who asked:
+   * attribution, never the principal the code runs as.
+   */
+  | { kind: "manual"; userId: string };
 
 /** The result shape of an operation that answers in response headers. */
 export interface HeaderResult {
@@ -862,6 +871,11 @@ export interface FunctionApi {
     "getSchema"(args: {
       "documentId": string | number;
     }): Promise<any>;
+    /** `documents.getSnapshot` — GET /documents/{documentId}/snapshots/{buildId}. One snapshot build with its verification result */
+    "getSnapshot"(args: {
+      "documentId": string | number;
+      "buildId": string | number;
+    }): Promise<any>;
     /** `documents.getStats` — GET /documents/{documentId}/stats. Document statistics (record/model/blob counts, approximate size) */
     "getStats"(args: {
       "documentId": string | number;
@@ -903,6 +917,12 @@ export interface FunctionApi {
     "listPendingInvitations"(args: {
       "documentId": string | number;
     }): Promise<any>;
+    /** `documents.listSnapshots` — GET /documents/{documentId}/snapshots. List a large document's snapshot builds, newest first */
+    "listSnapshots"(args: {
+      "documentId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
     /** `documents.open` — POST /documents/open. Open a document for collaboration (resolves access + alias) */
     "open"(args: {
       body: unknown;
@@ -1016,11 +1036,17 @@ export interface FunctionApi {
       "functionKey": string | number;
       body?: unknown;
     }): Promise<any>;
+    /** `functions.invokeAsSystem` — POST /functions/{functionKey}/invoke-as-system. Invoke a server function as the system, with no caller */
+    "invokeAsSystem"(args: {
+      "functionKey": string | number;
+      body?: unknown;
+    }): Promise<any>;
     /** `functions.logs` — GET /functions/{functionKey}/logs. List a server function's invocation logs, newest first */
     "logs"(args: {
       "functionKey": string | number;
       "limit"?: string | number | boolean;
       "cursor"?: string | number | boolean;
+      "runId"?: string | number | boolean;
     }): Promise<any>;
     /** `functions.start` — POST /functions/{functionKey}/start. Start a task function from inside another server function */
     "start"(args: {
@@ -1342,12 +1368,19 @@ export type FunctionOutput<K extends string> = K extends keyof FunctionSchemas
     : any
   : any;
 
-/** A declared function's mode, fixed at generation time. */
+/**
+ * A declared function's mode, fixed at generation time.
+ *
+ * `"any"` — the default when the authored file names no mode (#3454) — takes
+ * EITHER runner and the caller picks at call time; `"request"` and `"task"`
+ * lock it to one. An UNDECLARED key is the whole union, because nothing has
+ * said which of the three it is.
+ */
 export type FunctionMode<K extends string> = K extends keyof FunctionSchemas
   ? FunctionSchemas[K] extends { mode: infer M }
     ? M
-    : "request" | "task"
-  : "request" | "task";
+    : "request" | "task" | "any"
+  : "request" | "task" | "any";
 
 /**
  * The model names one database type addresses — its own, or any name at all
@@ -1358,9 +1391,38 @@ export type DatabaseModelNames<TModels> = [keyof TModels] extends [never]
   ? string
   : keyof TModels & string;
 
+/**
+ * A row as the platform HANDS IT BACK: whatever the schema declared, plus the
+ * record identity the platform owns (#3450).
+ *
+ * Every stored record has an `id`. A save that arrives without one is given a
+ * ULID, a projection always keeps it, and `delete` and `patch` take nothing
+ * else — so a function that queries a model and then moves one of its rows
+ * needs the id of the row it just read. A schema is free to say nothing about
+ * that field, and most do; the identity is the platform's, not the schema's,
+ * so it is added here rather than rendered into each declaration.
+ *
+ * A declared `id` is REPLACED, never intersected: one declared optional would
+ * stay optional on a read row it is always present on, and one declared with
+ * some other type would intersect to `never` and be unusable. The platform
+ * stamps a string whatever the schema says.
+ *
+ * An `any` row stays `any` — `DatabaseHandle<any>` is `defineQuery`'s default
+ * handle, and turning its rows into an object with one known member would
+ * narrow code that was deliberately left open.
+ *
+ * Writes are untouched: every one of them takes `Partial<TRow>`, so a row a
+ * function BUILDS still needs no id.
+ */
+export type PlatformRow<TRow> = 0 extends 1 & TRow
+  ? TRow
+  : Omit<TRow, "id"> & { id: string };
+
 /** One model's row shape, open when the type declares no schema. */
 export type DatabaseModelRow<TModels, M extends string> =
-  M extends keyof TModels ? TModels[M] : Record<string, unknown>;
+  M extends keyof TModels
+    ? PlatformRow<TModels[M]>
+    : Record<string, unknown> & { id: string };
 
 /**
  * One model of one database, scoped: the `modelName` every records call needs
@@ -1404,6 +1466,29 @@ export interface DatabaseModelHandle<TRow> {
   count(body?: ModelScopedBody): Promise<any>;
   aggregate(body: ModelScopedBody): Promise<any>;
   save(body: ModelScopedBody<{ id?: string; data: Partial<TRow>; [key: string]: unknown }>): Promise<any>;
+  /**
+   * Change some fields of ONE row — `databases.records.patch`, with this
+   * handle's model bound (#3450).
+   *
+   * The record id is positional and the body may not carry another, for the
+   * same reason it may not name another model: the runtime assigns both LAST,
+   * so a body that appeared to choose either would be a lie about which row
+   * moved. `condition`, `stringSets` and the rest of the operation's own keys
+   * pass through untouched.
+   */
+  patch(
+    recordId: string,
+    body: ModelScopedBody<{ data: Partial<TRow>; id?: never; [key: string]: unknown }>
+  ): Promise<any>;
+  /**
+   * Remove ONE row by the id a read handed back — `databases.records.delete`,
+   * with this handle's model bound (#3450). An optional `condition` makes it
+   * conditional, and travels untouched.
+   */
+  delete(
+    recordId: string,
+    body?: ModelScopedBody<{ condition?: Record<string, unknown>; id?: never }>
+  ): Promise<any>;
   /** Several writes to THIS model in one request; the binding is per item. */
   batch(body: {
     operations: Array<ModelBatchOperation<TRow>>;
@@ -1445,10 +1530,15 @@ export type DocumentModelNames = [keyof DocumentSchemas] extends [never]
   ? string
   : keyof DocumentSchemas & string;
 
-/** A document model's row shape, or an open record for an undeclared schema. */
+/**
+ * A document model's row shape, or an open record for an undeclared schema —
+ * carrying the platform's record identity either way (#3450), by the same rule
+ * and for the same reason as a database row: the records DO is one
+ * implementation, and `patch` and `delete` here take an id too.
+ */
 export type DocumentModelRow<M extends string> = M extends keyof DocumentSchemas
-  ? DocumentSchemas[M]
-  : Record<string, unknown>;
+  ? PlatformRow<DocumentSchemas[M]>
+  : Record<string, unknown> & { id: string };
 
 /** The options a document model read takes: a filter object (or its JSON), a page size, a cursor. */
 export interface DocumentQueryOptions {
@@ -1517,15 +1607,94 @@ export interface PromptRunArgs {
   configId?: string;
 }
 
-/** The member execute envelope, unchanged on the function path. */
-export interface PromptRunResult {
+/**
+ * The app's PROMPTS — EMPTY here and filled by the declaration
+ * `primitive config push` writes into the config tree's `functions/` directory
+ * (`primitive-prompt-types.d.ts`, from the tree's `prompts/*.toml`). A prompt
+ * that declares an `outputSchema` carries `{ output: <Key>PromptOutput }`; one
+ * that declares none carries `{}`, so reading `parsed.field` on it is a
+ * compile error rather than a runtime `undefined`.
+ */
+export interface PromptSchemas {}
+
+/** The keys `ctx.prompts.run` accepts — every declared one, or `string` before a push. */
+export type PromptKeys = [keyof PromptSchemas] extends [never]
+  ? string
+  : keyof PromptSchemas & string;
+
+/** One prompt's declared output type, or `unknown` where none is declared. */
+export type PromptOutput<K extends string> = K extends keyof PromptSchemas
+  ? PromptSchemas[K] extends { output: infer O }
+    ? O
+    : unknown
+  : unknown;
+
+/**
+ * Why a prompt's own answer was refused — #3330. Never set on a PROVIDER
+ * failure, which is what makes "the model returned the wrong shape"
+ * distinguishable from "the model failed".
+ */
+export type PromptOutputErrorCode =
+  | "PROMPT_OUTPUT_NOT_JSON"
+  | "PROMPT_OUTPUT_SCHEMA_VIOLATION";
+
+/** A prompt that declares an output shape, when the answer matched it. */
+export interface PromptRunSuccess<TParsed> {
+  success: true;
+  output: string;
+  /** The parsed, validated answer — no caller-side `JSON.parse` (#3330). */
+  parsed: TParsed;
+  error?: null;
+  errorCode?: null;
+  metrics?: Record<string, unknown>;
+  configId: string;
+}
+
+/**
+ * The failure arm, whichever failed. `errorCode` is set for a SHAPE failure
+ * and absent for a provider one; `output` carries the text either way, which
+ * is where the model's own value lives — a validation `error` names paths and
+ * schema constraints only.
+ */
+export interface PromptRunFailure {
+  success: false;
+  output: string;
+  error: string | null;
+  errorCode?: PromptOutputErrorCode | null;
+  parsed?: undefined;
+  metrics?: Record<string, unknown>;
+  configId: string;
+}
+
+/** The envelope for a key whose declaration says nothing about its output. */
+export interface PromptRunOpenResult {
   success: boolean;
   output: string;
+  /**
+   * Present when the config that ran declares `outputFormat = "json"` and the
+   * text parsed. Untyped: nothing declared its shape.
+   */
+  parsed?: unknown;
   error?: string | null;
+  errorCode?: PromptOutputErrorCode | null;
   metrics?: Record<string, unknown>;
   configId: string;
 }
 
+/**
+ * The member execute envelope, plus what the prompt's own declaration adds.
+ *
+ * For a key whose `prompts/<key>.toml` declares an `outputSchema`, this is a
+ * discriminated union: narrow on `success` and `parsed` is the declared type,
+ * required. For every other key — and in a tree that has not pushed — it is
+ * the open shape, with `parsed` optional and `unknown`.
+ */
+export type PromptRunResult<K extends string = string> = K extends keyof PromptSchemas
+  ? PromptSchemas[K] extends { output: infer O }
+    ? PromptRunSuccess<O> | PromptRunFailure
+    : PromptRunOpenResult
+  : PromptRunOpenResult;
+
 /** What a send delivered to. */
 export interface SendResult {
   /** Unique live connections the frame was sent to. Zero is a success. */
@@ -1673,14 +1842,33 @@ export interface FunctionContext {
     ): Promise<FunctionStartResult>;
   };
   /**
-   * Run one of the app's prompts, under a `prompt:<key>` grant (#3183).
+   * Run one of the app's prompts, with nothing to declare (#3183, #3279).
    *
    * The prompt's `accessRule` is not consulted — it states which MEMBERS may
-   * execute the prompt from a client, and the grant is what authorizes this
-   * call. The provider request is bounded by the invocation's own deadline.
+   * execute the prompt from a client, and the invocation gate is what
+   * authorized this call. The provider request is bounded by the invocation's
+   * own deadline.
+   *
+   * TYPED BY KEY (#3330). Where `prompts/<key>.toml` declares an
+   * `outputSchema`, the platform parses the answer, validates it against that
+   * schema and hands it back as `parsed`, typed — so the shape is written once
+   * in TOML instead of restated as a `JSON.parse` at every call site. Where
+   * only the config that ran declares `outputFormat = "json"`, `parsed` is
+   * present but `unknown`. Where neither is declared the envelope is exactly
+   * what it has always been.
+   *
+   * A shape the declaration refuses is `success: false` with an `errorCode`
+   * (`PROMPT_OUTPUT_NOT_JSON` or `PROMPT_OUTPUT_SCHEMA_VIOLATION`) and the
+   * text still in `output`; a PROVIDER failure has `error` and no
+   * `errorCode`, so the two are told apart without guessing.
+   *
+   * Once a tree has pushed, a key it does not declare is a compile error.
    */
   prompts: {
-    run(promptKey: string, args?: PromptRunArgs): Promise<PromptRunResult>;
+    run<K extends PromptKeys>(
+      promptKey: K,
+      args?: PromptRunArgs
+    ): Promise<PromptRunResult<K>>;
   };
   /**
    * The value of one app secret, under a `secret:<NAME>` grant (#3183).
@@ -1750,13 +1938,22 @@ export interface FunctionContext {
 }
 
 /**
- * The durable step handle — Cloudflare Workflows' `WorkflowStep`, forwarded
- * untouched, so `step.do` results are memoized and `step.sleep` hibernates.
+ * The step handle. `step` is the third argument under BOTH runners, so the
+ * same body runs either way — which is what `mode = "any"` is for (#3454).
+ *
+ * Under the TASK runner it is Cloudflare Workflows' `WorkflowStep`, forwarded
+ * untouched: `step.do` results are memoized and replayed, and `step.sleep`
+ * hibernates.
  *
- * A SYNCHRONOUS invocation gets a passthrough shim of the same shape, so a body
- * written for durable mode runs either way: `do` executes the body (nothing to
- * memoize into without an engine), `sleep` resolves immediately (the sync
- * ceiling is seconds), and `waitForEvent` throws `STEP_NOT_AVAILABLE`.
+ * Under the REQUEST runner it is the platform's own, bounded by the request's
+ * clock: `do` executes the body inline (there is no engine to memoize into,
+ * and nothing is replayed); `sleep` and `sleepUntil` REALLY wait when the
+ * remaining request budget covers the duration, and otherwise fail the
+ * invocation with `errorCode: "FUNCTION_STEP_NEEDS_TASK"` saying to start the
+ * function as a task; `waitForEvent` fails the same way, because nothing can
+ * deliver an event to an invocation that has to return now. The thrown error's
+ * `name` is `STEP_NOT_AVAILABLE` in every case, so a body that catches it
+ * keeps catching it.
  */
 export interface FunctionStep {
   do<T>(name: string, body: () => T | Promise<T>): Promise<T>;
@@ -1778,10 +1975,12 @@ export declare const SDK_STUB_VERSION: string;
 /**
  * The handler a function exports, typed for one declared key.
  *
- * `step` is the third argument in BOTH modes (#3186). A task run gets the
- * engine's live `WorkflowStep`; a request invocation gets a passthrough shim
- * (`do` runs the body, `sleep` resolves at once, `waitForEvent` throws a
- * named error), so a task-authored body can be exercised as a request.
+ * `step` is the third argument under BOTH runners (#3186, #3454). A task run
+ * gets the engine's live `WorkflowStep`; a request invocation gets the
+ * platform's own, where `do` runs the body inline and a wait the request
+ * budget cannot cover fails the invocation naming the task runner — so a
+ * task-authored body can be exercised as a request, and the one place the two
+ * genuinely differ says so rather than pretending.
  */
 export type FunctionHandler<TInput, TOutput> = (
   input: TInput,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primitive-functions",
-  "version": "0.2.0-alpha.6",
+  "version": "0.2.0-alpha.8",
   "description": "The module a Primitive server function imports. Supplied by the platform at invoke time; reserved here so the name is ours before the runtime lands.",
   "license": "UNLICENSED",
   "author": "Primitive LLC",