primitive-functions 0.2.0-alpha.1 → 0.2.0-alpha.2

package/index.d.ts

@@ -10,16 +10,34 @@
  * time, and reaching the stub means it did not.
  */
 
-/** The signed-in user on whose behalf the invocation runs. */
+/**
+ * The signed-in user who invoked the function over HTTP.
+ *
+ * Attribution, never authority (#3279): function code acts as the system
+ * whoever called it, so this says WHO asked, and the rows the function writes
+ * are attributed to them. A trigger fire has no caller and `ctx.user` is
+ * null.
+ */
 export interface FunctionUser {
   userId: string;
   email: string | null;
 }
 
-/** What started this invocation. Only `http` exists today. */
-export interface FunctionTrigger {
-  kind: "http";
-}
+/** What started this invocation. */
+export type FunctionTrigger =
+  | { kind: "http" }
+  | { kind: "webhook"; [key: string]: unknown }
+  | { kind: "cron"; [key: string]: unknown }
+  | { kind: "database"; databaseId: string; databaseType: string; [key: string]: unknown }
+  /**
+   * A DSL workflow's `workflow.call` step reached this function (#3288).
+   *
+   * TRANSITIONAL: the bridge exists so a workflow tree can migrate leaf-first
+   * during the transition, and it retires with the workflow engine in phase 7,
+   * taking this variant with it. `workflowKey` names the PARENT workflow, and
+   * `runId`/`stepId` locate the step inside its run.
+   */
+  | { kind: "workflow"; workflowKey: string; runId: string; stepId: string };
 
 /** The result shape of an operation that answers in response headers. */
 export interface HeaderResult {
@@ -39,16 +57,19 @@ export interface PrimitivePlatformError extends Error {
 
 /**
  * The typed HTTP profile, generated from the platform's OpenAPI document. Its
- * namespaces mirror the operation ids: analytics, blobBuckets, collections, configVars, connections, databaseTypeConfigs, databases, documents, email, functions, gemini, groups, integrations, iterations, llm, locks, notifications, prompts, resourceMetadata, secrets, users.
+ * namespaces mirror the operation ids: analytics, blobBuckets, channels, collections, configVars, connections, databaseTypeConfigs, databases, documents, email, functions, gemini, groups, integrations, iterations, llm, locks, notifications, prompts, resourceMetadata, secrets, users.
  * Methods take one options object carrying the operation's path parameters,
  * query parameters, request headers (under their wire names) and `body`.
  *
  * Generated from the same operations as the runtime profile, so a method that
  * type-checks is a method the platform publishes — and a missing path
  * parameter or a missing required header is a compile error rather than a
- * `TypeError` at invoke time. Namespaces the GATEWAY does not yet allow are
- * still declared: they exist, they answer the gateway's structured denial, and
- * hiding them would make a route's availability look like a typo.
+ * `TypeError` at invoke time. Every call runs with the app's own SYSTEM
+ * authority (#3279): the invocation gate was the authorization. The three
+ * namespaces the gateway does not admit (`functions`, `iterations`,
+ * `databaseTypeConfigs`) are still declared: they exist, they answer the
+ * gateway's structured denial, and hiding them would make a route's
+ * availability look like a typo.
  */
 export interface FunctionApi {
   "analytics": {
@@ -233,6 +254,18 @@ export interface FunctionApi {
       body: ArrayBuffer | Uint8Array | string;
     }): Promise<any>;
   };
+  "channels": {
+    /** `channels.authorize` — POST /channels/{channel}/grants. Issue a channel grant under a server function's grant */
+    "authorize"(args: {
+      "channel": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `channels.publish` — POST /channels/{channel}/publish. Publish a message to a channel under a server function's grant */
+    "publish"(args: {
+      "channel": string | number;
+      body: unknown;
+    }): Promise<any>;
+  };
   "collections": {
     /** `collections.addDocument` — POST /collections/{collectionId}/documents. Add a document to a collection */
     "addDocument"(args: {
@@ -847,6 +880,7 @@ export interface FunctionApi {
       "count"(args: {
         "documentId": string | number;
         "model": string | number;
+        "filter"?: Record<string, unknown> | string;
       }): Promise<any>;
       /** `documents.records.delete` — DELETE /documents/{documentId}/records/{model}/{recordId}. Delete a record from a document model */
       "delete"(args: {
@@ -865,6 +899,9 @@ export interface FunctionApi {
       "query"(args: {
         "documentId": string | number;
         "model": string | number;
+        "limit"?: string | number | boolean;
+        "cursor"?: string | number | boolean;
+        "filter"?: Record<string, unknown> | string;
       }): Promise<any>;
       /** `documents.records.save` — POST /documents/{documentId}/records/{model}. Create or replace a record in a document model */
       "save"(args: {
@@ -1364,8 +1401,29 @@ export interface SendResult {
   truncated: boolean;
 }
 
+/** Who a channel grant is for, and for how long — #3184. */
+export interface ChannelAuthorizeOptions {
+  /**
+   * The member the grant names. Caller mode defaults to the invoking caller;
+   * system mode has no caller and must say.
+   */
+  userId?: string;
+  /** Default 300 s, clamped to the platform ceiling of 900 s. */
+  ttlSeconds?: number;
+}
+
+/** The credential a client presents on the WebSocket it already has. */
+export interface ChannelGrantResult {
+  channel: string;
+  /** The signed grant. Hand it to the client; it is not readable here. */
+  grant: string;
+  /** Epoch milliseconds. Expiry is the only revocation a channel has. */
+  expiresAt: number;
+}
+
 export interface FunctionContext {
-  user: FunctionUser;
+  /** The HTTP caller, or null for a webhook, cron or database-change fire. */
+  user: FunctionUser | null;
   trigger: FunctionTrigger;
   api: FunctionApi;
   /**
@@ -1433,6 +1491,23 @@ export interface FunctionContext {
   connections: {
     send(connectionId: string, payload: unknown): Promise<SendResult>;
   };
+  /**
+   * Realtime channels, under a `channel:<namespace>` grant that COVERS the
+   * channel — #3184.
+   *
+   * `authorize` hands back a short-lived grant for ONE member to present on
+   * the socket it already has; `publish` delivers a `channel.message` frame to
+   * every connection that has joined and whose grant has not expired. Expiry is
+   * the only revocation, so `expiresAt` comes back for the client to renew
+   * ahead of — a renewal is another authorize and another subscribe.
+   */
+  channels: {
+    authorize(
+      channel: string,
+      options?: ChannelAuthorizeOptions
+    ): Promise<ChannelGrantResult>;
+    publish(channel: string, payload: unknown): Promise<SendResult>;
+  };
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "primitive-functions",
-  "version": "0.2.0-alpha.1",
+  "version": "0.2.0-alpha.2",
   "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",