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

package/index.d.ts

@@ -39,7 +39,7 @@ export interface PrimitivePlatformError extends Error {
 
 /**
  * The typed HTTP profile, generated from the platform's OpenAPI document. Its
- * namespaces mirror the operation ids: databaseTypeConfigs, databases, documents, functions.
+ * 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.
  * Methods take one options object carrying the operation's path parameters,
  * query parameters, request headers (under their wire names) and `body`.
  *
@@ -51,6 +51,274 @@ export interface PrimitivePlatformError extends Error {
  * hiding them would make a route's availability look like a typo.
  */
 export interface FunctionApi {
+  "analytics": {
+    /** `analytics.cohortRetention` — GET /analytics/cohort-retention. Cohort retention metrics */
+    "cohortRetention"(args?: {
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.dailyActive` — GET /analytics/daily-active. Daily active user time series */
+    "dailyActive"(args?: {
+      "windowDays"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.errorGroups` — GET /analytics/errors/groups. Group failure events by fingerprint with per-day count buckets */
+    "errorGroups"(args?: {
+      "windowDays"?: string | number | boolean;
+      "limit"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+      "filter"?: Record<string, Record<string, string | number | boolean | Array<string | number | boolean>>>;
+    }): Promise<any>;
+    /** `analytics.integrationUsage` — GET /analytics/integrations. Integration usage metrics */
+    "integrationUsage"(args?: {
+      "windowDays"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.listEvents` — GET /analytics/events. List analytics events */
+    "listEvents"(args?: {
+      "windowDays"?: string | number | boolean;
+      "page"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+      "filter"?: Record<string, Record<string, string | number | boolean | Array<string | number | boolean>>>;
+    }): Promise<any>;
+    /** `analytics.listEventsGrouped` — GET /analytics/events/grouped. List analytics events grouped by dimension */
+    "listEventsGrouped"(args?: {
+      "windowDays"?: string | number | boolean;
+      "groupBy"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+      "filter"?: Record<string, Record<string, string | number | boolean | Array<string | number | boolean>>>;
+    }): Promise<any>;
+    /** `analytics.overviewDau` — GET /analytics/overview/dau. Daily active users overview */
+    "overviewDau"(args?: {
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.overviewGrowth` — GET /analytics/overview/growth. User growth overview */
+    "overviewGrowth"(args?: {
+      "windowDays"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.overviewMau` — GET /analytics/overview/mau. Monthly active users overview */
+    "overviewMau"(args?: {
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.overviewWau` — GET /analytics/overview/wau. Weekly active users overview */
+    "overviewWau"(args?: {
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.rollingActive` — GET /analytics/rolling-active. Rolling active user time series */
+    "rollingActive"(args?: {
+      "windowDays"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.searchUsers` — GET /analytics/users/search. Search app users for analytics */
+    "searchUsers"(args?: {
+      "q"?: string | number | boolean;
+      "limit"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.topPrompts` — GET /analytics/prompts/top. List the most-executed prompts */
+    "topPrompts"(args?: {
+      "windowDays"?: string | number | boolean;
+      "limit"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.topUsers` — GET /analytics/users/top. List the most active users */
+    "topUsers"(args?: {
+      "windowDays"?: string | number | boolean;
+      "limit"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.topWorkflows` — GET /analytics/workflows/top. List the most-run workflows */
+    "topWorkflows"(args?: {
+      "windowDays"?: string | number | boolean;
+      "limit"?: string | number | boolean;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.userDetail` — GET /analytics/users/{userUlid}/detail. Detailed analytics for a single user */
+    "userDetail"(args: {
+      "userUlid": string | number;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.userSnapshot` — GET /analytics/users/{userUlid}/snapshot. Activity snapshot for a single user */
+    "userSnapshot"(args: {
+      "userUlid": string | number;
+      "current_timestamp"?: string | number | boolean;
+      "_bust"?: string | number | boolean;
+    }): Promise<any>;
+    /** `analytics.writeForUser` — POST /analytics/write-for-user. Write an analytics event for a subject user under a grant */
+    "writeForUser"(args: {
+      body: unknown;
+    }): Promise<any>;
+  };
+  "blobBuckets": {
+    /** `blobBuckets.createBucket` — POST /blob-buckets. Create a blob bucket */
+    "createBucket"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `blobBuckets.delete` — DELETE /blob-buckets/{bucketId}/blobs/{blobId}. Delete a blob */
+    "delete"(args: {
+      "bucketId": string | number;
+      "blobId": string | number;
+    }): Promise<any>;
+    /** `blobBuckets.deleteBatch` — POST /blob-buckets/{bucketId}/blobs/delete. Batch delete blobs from a bucket */
+    "deleteBatch"(args: {
+      "bucketId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `blobBuckets.deleteBucket` — DELETE /blob-buckets/{bucketId}. Delete a blob bucket */
+    "deleteBucket"(args: {
+      "bucketId": string | number;
+    }): Promise<any>;
+    /** `blobBuckets.download` — GET /blob-buckets/{bucketId}/blobs/{blobId}. Download a blob (anonymous allowed for public buckets) */
+    "download"(args: {
+      "bucketId": string | number;
+      "blobId": string | number;
+      "disposition"?: string | number | boolean;
+    }): Promise<Uint8Array>;
+    /** `blobBuckets.downloadSigned` — GET /blob-buckets/{bucketId}/blobs/{blobId}/signed. Download a blob via a signed URL token */
+    "downloadSigned"(args: {
+      "bucketId": string | number;
+      "blobId": string | number;
+      "token"?: string | number | boolean;
+    }): Promise<Uint8Array>;
+    /** `blobBuckets.getBucket` — GET /blob-buckets/{bucketId}. Get a blob bucket by id */
+    "getBucket"(args: {
+      "bucketId": string | number;
+    }): Promise<any>;
+    /** `blobBuckets.getMetadata` — GET /blob-buckets/{bucketId}/blobs/{blobId}/metadata. Get blob metadata (anonymous allowed for public buckets) */
+    "getMetadata"(args: {
+      "bucketId": string | number;
+      "blobId": string | number;
+    }): Promise<any>;
+    /** `blobBuckets.getSignedUrl` — POST /blob-buckets/{bucketId}/blobs/{blobId}/signed-url. Create a signed download URL for a blob */
+    "getSignedUrl"(args: {
+      "bucketId": string | number;
+      "blobId": string | number;
+      body?: unknown;
+    }): Promise<any>;
+    /** `blobBuckets.list` — GET /blob-buckets/{bucketId}/blobs. List blobs in a bucket (anonymous allowed for public buckets) */
+    "list"(args: {
+      "bucketId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
+    /** `blobBuckets.listBuckets` — GET /blob-buckets. List blob buckets */
+    "listBuckets"(args?: Record<string, never>): Promise<any>;
+    /** `blobBuckets.updateBucket` — PATCH /blob-buckets/{bucketId}. Update a blob bucket */
+    "updateBucket"(args: {
+      "bucketId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `blobBuckets.upload` — POST /blob-buckets/{bucketId}/blobs. Upload a blob to a bucket */
+    "upload"(args: {
+      "bucketId": string | number;
+      "X-Blob-Filename": string | number;
+      "X-Blob-Tags"?: string | number;
+      "Content-Type"?: string | number;
+      body: ArrayBuffer | Uint8Array | string;
+    }): Promise<any>;
+  };
+  "collections": {
+    /** `collections.addDocument` — POST /collections/{collectionId}/documents. Add a document to a collection */
+    "addDocument"(args: {
+      "collectionId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `collections.addMember` — POST /collections/{collectionId}/members. Add a member to a collection */
+    "addMember"(args: {
+      "collectionId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `collections.create` — POST /collections. Create a collection */
+    "create"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `collections.delete` — DELETE /collections/{collectionId}. Delete a collection */
+    "delete"(args: {
+      "collectionId": string | number;
+    }): Promise<any>;
+    /** `collections.get` — GET /collections/{collectionId}. Get a collection by id */
+    "get"(args: {
+      "collectionId": string | number;
+    }): Promise<any>;
+    /** `collections.getAccess` — GET /collections/{collectionId}/access. Get a collection's access summary */
+    "getAccess"(args: {
+      "collectionId": string | number;
+    }): Promise<any>;
+    /** `collections.grantGroupPermission` — POST /collections/{collectionId}/group-permissions. Grant a group permission on a collection */
+    "grantGroupPermission"(args: {
+      "collectionId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `collections.list` — GET /collections. List collections */
+    "list"(args?: {
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
+    /** `collections.listCollectionsForDocument` — GET /documents/{documentId}/collections. List collections a document belongs to (reverse lookup) */
+    "listCollectionsForDocument"(args: {
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `collections.listDocuments` — GET /collections/{collectionId}/documents. List documents in a collection */
+    "listDocuments"(args: {
+      "collectionId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
+    /** `collections.listPendingInvitations` — GET /collections/{collectionId}/pending-invitations. List a collection's pending invitations */
+    "listPendingInvitations"(args: {
+      "collectionId": string | number;
+    }): Promise<any>;
+    /** `collections.removeDocument` — DELETE /collections/{collectionId}/documents/{documentId}. Remove a document from a collection */
+    "removeDocument"(args: {
+      "collectionId": string | number;
+      "documentId": string | number;
+    }): Promise<any>;
+    /** `collections.removeMember` — DELETE /collections/{collectionId}/members/{userId}. Remove a member from a collection */
+    "removeMember"(args: {
+      "collectionId": string | number;
+      "userId": string | number;
+    }): Promise<any>;
+    /** `collections.revokeGroupPermission` — DELETE /collections/{collectionId}/group-permissions/{groupType}/{groupId}. Revoke a group permission on a collection */
+    "revokeGroupPermission"(args: {
+      "collectionId": string | number;
+      "groupType": string | number;
+      "groupId": string | number;
+    }): Promise<any>;
+    /** `collections.update` — PATCH /collections/{collectionId}. Update a collection */
+    "update"(args: {
+      "collectionId": string | number;
+      body: unknown;
+    }): Promise<any>;
+  };
+  "configVars": {
+    /** `configVars.get` — GET /config-vars/{name}. Read an app config var under a server function's grants */
+    "get"(args: {
+      "name": string | number;
+    }): Promise<any>;
+  };
+  "connections": {
+    /** `connections.send` — POST /connections/{connectionId}/send. Send a realtime message to one connection of this app */
+    "send"(args: {
+      "connectionId": string | number;
+      body: unknown;
+    }): Promise<any>;
+  };
   "databaseTypeConfigs": {
     /** `databaseTypeConfigs.create` — POST /databases/types. Create a database type */
     "create"(args: {
@@ -341,6 +609,12 @@ export interface FunctionApi {
       "databaseId": string | number;
       "userId": string | number;
     }): Promise<any>;
+    /** `databases.runOperation` — POST /databases/{databaseId}/operations/{name}/run. Run a database operation under a server function's grants */
+    "runOperation"(args: {
+      "databaseId": string | number;
+      "name": string | number;
+      body?: unknown;
+    }): Promise<any>;
     /** `databases.transferOwnership` — POST /databases/{databaseId}/permissions/transfer. Transfer database ownership */
     "transferOwnership"(args: {
       "databaseId": string | number;
@@ -439,11 +713,6 @@ export interface FunctionApi {
     "create"(args: {
       body: unknown;
     }): Promise<any>;
-    /** `documents.createInvitation` — POST /documents/{documentId}/invitations. Send an invitation to collaborate on a document */
-    "createInvitation"(args: {
-      "documentId": string | number;
-      body: unknown;
-    }): Promise<any>;
     /** `documents.createWithAlias` — POST /documents/create-with-alias. Create a document and bind it to an alias */
     "createWithAlias"(args: {
       body: unknown;
@@ -475,20 +744,10 @@ export interface FunctionApi {
     "debugStats"(args: {
       "documentId": string | number;
     }): Promise<any>;
-    /** `documents.declineInvitation` — POST /documents/{documentId}/invitations/{invitationId}/decline. Decline a document invitation (invitee only) */
-    "declineInvitation"(args: {
-      "documentId": string | number;
-      "invitationId": string | number;
-    }): Promise<any>;
     /** `documents.delete` — DELETE /documents/{documentId}. Delete a document */
     "delete"(args: {
       "documentId": string | number;
     }): Promise<any>;
-    /** `documents.deleteInvitation` — DELETE /documents/{documentId}/invitations/{invitationId}. Cancel a pending document invitation */
-    "deleteInvitation"(args: {
-      "documentId": string | number;
-      "invitationId": string | number;
-    }): Promise<any>;
     /** `documents.denyAccessRequest` — POST /documents/{documentId}/access-requests/{requestId}/deny. Deny a document access request */
     "denyAccessRequest"(args: {
       "documentId": string | number;
@@ -556,8 +815,6 @@ export interface FunctionApi {
       "documentId": string | number;
       body: unknown;
     }): Promise<any>;
-    /** `documents.list` — GET /documents. List documents the caller can access */
-    "list"(args?: Record<string, never>): Promise<any>;
     /** `documents.listAccessRequests` — GET /documents/{documentId}/access-requests. List access requests for a document */
     "listAccessRequests"(args: {
       "documentId": string | number;
@@ -566,10 +823,6 @@ export interface FunctionApi {
     "listGroupPermissions"(args: {
       "documentId": string | number;
     }): Promise<any>;
-    /** `documents.listInvitations` — GET /documents/{documentId}/invitations. List invitations issued for a document */
-    "listInvitations"(args: {
-      "documentId": string | number;
-    }): Promise<any>;
     /** `documents.listPendingInvitations` — GET /documents/{documentId}/pending-invitations. List a document's pending (deferred) invitations */
     "listPendingInvitations"(args: {
       "documentId": string | number;
@@ -666,24 +919,544 @@ export interface FunctionApi {
       "documentId": string | number;
       body: unknown;
     }): Promise<any>;
-    /** `documents.validateAccess` — POST /documents/{documentId}/validate-access. Validate access to a document (accepts/upgrades pending invitations) */
+    /** `documents.validateAccess` — POST /documents/{documentId}/validate-access. Resolve the caller's effective access level for a document */
     "validateAccess"(args: {
       "documentId": string | number;
     }): Promise<any>;
   };
+  "email": {
+    /** `email.send` — POST /emails/send. Send an application email under a server function's grant */
+    "send"(args: {
+      body: unknown;
+    }): Promise<any>;
+  };
   "functions": {
-    /** `functions.invoke` — POST /functions/{functionKey}. Invoke a server function synchronously and return its result */
+    /** `functions.invoke` — POST /functions/{functionKey}. Invoke a server function: a synchronous one returns its result, a durable one starts a run */
     "invoke"(args: {
       "functionKey": string | number;
       body?: unknown;
     }): Promise<any>;
   };
+  "gemini": {
+    /** `gemini.countTokens` — POST /gemini/count-tokens. Count tokens for a Gemini request */
+    "countTokens"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `gemini.generate` — POST /gemini/generate. Generate content with Gemini */
+    "generate"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `gemini.generateRaw` — POST /gemini/generate-raw. Generate content with Gemini (raw passthrough) */
+    "generateRaw"(args: {
+      "model"?: string | number | boolean;
+      body: unknown;
+    }): Promise<any>;
+    /** `gemini.models` — GET /gemini/models. List available Gemini models */
+    "models"(args?: Record<string, never>): Promise<any>;
+  };
+  "groups": {
+    /** `groups.addMember` — POST /groups/{groupType}/{groupId}/members. Add a member to a group */
+    "addMember"(args: {
+      "groupType": string | number;
+      "groupId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `groups.create` — POST /groups. Create a group */
+    "create"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `groups.delete` — DELETE /groups/{groupType}/{groupId}. Delete a group */
+    "delete"(args: {
+      "groupType": string | number;
+      "groupId": string | number;
+    }): Promise<any>;
+    /** `groups.get` — GET /groups/{groupType}/{groupId}. Get a group by type and id */
+    "get"(args: {
+      "groupType": string | number;
+      "groupId": string | number;
+    }): Promise<any>;
+    /** `groups.list` — GET /groups. List groups */
+    "list"(args?: {
+      "type"?: string | number | boolean;
+      "includeSystem"?: string | number | boolean;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
+    /** `groups.listDatabases` — GET /groups/{groupType}/{groupId}/databases. List databases shared with a group */
+    "listDatabases"(args: {
+      "groupType": string | number;
+      "groupId": string | number;
+    }): Promise<any>;
+    /** `groups.listDocuments` — GET /groups/{groupType}/{groupId}/documents. List documents shared with a group */
+    "listDocuments"(args: {
+      "groupType": string | number;
+      "groupId": string | number;
+    }): Promise<any>;
+    /** `groups.listMembers` — GET /groups/{groupType}/{groupId}/members. List a group's members */
+    "listMembers"(args: {
+      "groupType": string | number;
+      "groupId": string | number;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+      "include"?: string | number | boolean;
+    }): Promise<any>;
+    /** `groups.listPendingInvitations` — GET /groups/{groupType}/{groupId}/pending-invitations. List a group's pending invitations */
+    "listPendingInvitations"(args: {
+      "groupType": string | number;
+      "groupId": string | number;
+    }): Promise<any>;
+    /** `groups.listUserMemberships` — GET /users/{userId}/memberships. List a user's group memberships */
+    "listUserMemberships"(args: {
+      "userId": string | number;
+      "includeSystem"?: string | number | boolean;
+      "type"?: string | number | boolean;
+    }): Promise<any>;
+    /** `groups.removeMember` — DELETE /groups/{groupType}/{groupId}/members/{userId}. Remove a specific member from a group */
+    "removeMember"(args: {
+      "groupType": string | number;
+      "groupId": string | number;
+      "userId": string | number;
+    }): Promise<any>;
+    /** `groups.removeMemberByEmail` — DELETE /groups/{groupType}/{groupId}/members. Remove a group member or pending invitation by email */
+    "removeMemberByEmail"(args: {
+      "groupType": string | number;
+      "groupId": string | number;
+      "email"?: string | number | boolean;
+    }): Promise<any>;
+    /** `groups.update` — PATCH /groups/{groupType}/{groupId}. Update a group */
+    "update"(args: {
+      "groupType": string | number;
+      "groupId": string | number;
+      body: unknown;
+    }): Promise<any>;
+  };
+  "integrations": {
+    /** `integrations.call` — POST /integrations/{integrationKey}/call. Call an integration under a server function's grants */
+    "call"(args: {
+      "integrationKey": string | number;
+      body?: unknown;
+    }): Promise<any>;
+    /** `integrations.list` — GET /integrations. List integrations configured for the app */
+    "list"(args?: Record<string, never>): Promise<any>;
+    /** `integrations.proxy` — POST /integrations/{integrationKey}/proxy. Proxy a request through a configured integration */
+    "proxy"(args: {
+      "integrationKey": string | number;
+    }): Promise<any>;
+  };
+  "iterations": {
+    /** `iterations.get` — GET /iterations/{iterationName}. Get details for a single iteration */
+    "get"(args: {
+      "iterationName": string | number;
+    }): Promise<any>;
+    /** `iterations.list` — GET /iterations. List iteration runs */
+    "list"(args?: Record<string, never>): Promise<any>;
+    /** `iterations.reset` — POST /iterations/{iterationName}/reset. Reset a terminal iteration so the next trigger runs fresh */
+    "reset"(args: {
+      "iterationName": string | number;
+    }): Promise<any>;
+  };
+  "llm": {
+    /** `llm.chat` — POST /llm/chat. Run an LLM chat completion */
+    "chat"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `llm.models` — GET /llm/models. List available LLM models */
+    "models"(args?: Record<string, never>): Promise<any>;
+  };
+  "locks": {
+    /** `locks.list` — GET /locks. List all currently-held named locks in the app */
+    "list"(args?: Record<string, never>): Promise<any>;
+    /** `locks.release` — POST /locks/release. Release a held named lock (requires the acquire handle) */
+    "release"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `locks.renew` — POST /locks/renew. Extend the lease on a held named lock */
+    "renew"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `locks.status` — POST /locks/status. Report the current holder of a named lock */
+    "status"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `locks.tryAcquire` — POST /locks/acquire. Attempt to acquire a named lock (single non-blocking attempt) */
+    "tryAcquire"(args: {
+      body: unknown;
+    }): Promise<any>;
+  };
+  "notifications": {
+    /** `notifications.list` — GET /notifications. List the caller's in-app notification inbox (newest first) */
+    "list"(args?: {
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
+    /** `notifications.listDevices` — GET /me/push-tokens. List the caller's registered push devices */
+    "listDevices"(args?: Record<string, never>): Promise<any>;
+    /** `notifications.markAllRead` — POST /notifications/read-all. Mark all of the caller's notifications as read */
+    "markAllRead"(args?: Record<string, never>): Promise<any>;
+    /** `notifications.markRead` — PATCH /notifications/{notificationId}/read. Mark one of the caller's notifications as read */
+    "markRead"(args: {
+      "notificationId": string | number;
+    }): Promise<any>;
+    /** `notifications.registerDevice` — POST /me/push-tokens. Register (upsert) the caller's device push token */
+    "registerDevice"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `notifications.send` — POST /notifications/send. Send a notification to an app user (durable in-app inbox row + live WS frame) */
+    "send"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `notifications.unreadCount` — GET /notifications/unread-count. Count the caller's unread notifications */
+    "unreadCount"(args?: Record<string, never>): Promise<any>;
+    /** `notifications.unregisterDevice` — DELETE /me/push-tokens/{token}. Unregister one of the caller's device push tokens */
+    "unregisterDevice"(args: {
+      "token": string | number;
+    }): Promise<any>;
+  };
+  "prompts": {
+    /** `prompts.execute` — POST /prompts/{promptKey}/execute. Execute a saved prompt */
+    "execute"(args: {
+      "promptKey": string | number;
+    }): Promise<any>;
+    /** `prompts.run` — POST /prompts/{promptKey}/run. Run a prompt under a server function's grants */
+    "run"(args: {
+      "promptKey": string | number;
+      body?: unknown;
+    }): Promise<any>;
+  };
+  "resourceMetadata": {
+    /** `resourceMetadata.delete` — DELETE /resources/{resourceType}/{resourceId}/metadata/{category}. Delete a resource's metadata for a category (idempotent) */
+    "delete"(args: {
+      "resourceType": string | number;
+      "resourceId": string | number;
+      "category": string | number;
+    }): Promise<any>;
+    /** `resourceMetadata.get` — GET /resources/{resourceType}/{resourceId}/metadata/{category}. Read a resource's metadata for a category */
+    "get"(args: {
+      "resourceType": string | number;
+      "resourceId": string | number;
+      "category": string | number;
+    }): Promise<any>;
+    /** `resourceMetadata.getBatch` — POST /resources/metadata/batch. Batch-read resource metadata (partial success) */
+    "getBatch"(args: {
+      "debug"?: string | number | boolean;
+      body: unknown;
+    }): Promise<any>;
+    /** `resourceMetadata.list` — GET /resources/{resourceType}/{resourceId}/metadata. List all metadata categories on a resource */
+    "list"(args: {
+      "resourceType": string | number;
+      "resourceId": string | number;
+    }): Promise<any>;
+    /** `resourceMetadata.resolve` — POST /metadata/resolve. Resolve a resource by a category's unique metadata value */
+    "resolve"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `resourceMetadata.set` — PUT /resources/{resourceType}/{resourceId}/metadata/{category}. Write a resource's metadata for a category */
+    "set"(args: {
+      "resourceType": string | number;
+      "resourceId": string | number;
+      "category": string | number;
+      body: unknown;
+    }): Promise<any>;
+  };
+  "secrets": {
+    /** `secrets.get` — GET /secrets/{name}. Read an app secret under a server function's grants */
+    "get"(args: {
+      "name": string | number;
+    }): Promise<any>;
+  };
+  "users": {
+    /** `users.getBasic` — GET /users/{userId}/basic. Get a user's basic public profile */
+    "getBasic"(args: {
+      "userId": string | number;
+    }): Promise<any>;
+    /** `users.getProfiles` — POST /users/profiles. Look up user profiles in bulk */
+    "getProfiles"(args: {
+      body: unknown;
+    }): Promise<any>;
+    /** `users.list` — GET /users. List app users */
+    "list"(args?: {
+      "email"?: string | number | boolean;
+      "userId"?: string | number | boolean;
+      "name"?: string | number | boolean;
+      "limit"?: string | number | boolean;
+      "cursor"?: string | number | boolean;
+    }): Promise<any>;
+    /** `users.lookup` — GET /users/lookup. Look up a user by identifier */
+    "lookup"(args?: {
+      "email"?: string | number | boolean;
+    }): Promise<any>;
+    /** `users.remove` — DELETE /users/{userId}. Remove a user from the app */
+    "remove"(args: {
+      "userId": string | number;
+    }): Promise<any>;
+    /** `users.send` — POST /users/{userId}/send. Send a realtime message to a member of this app */
+    "send"(args: {
+      "userId": string | number;
+      body: unknown;
+    }): Promise<any>;
+    /** `users.setRole` — PUT /users/{userId}/role. Set a user's app role */
+    "setRole"(args: {
+      "userId": string | number;
+      body: unknown;
+    }): Promise<any>;
+  };
+}
+
+/**
+ * The app's database types, model by model — EMPTY here and filled by the
+ * declaration `primitive config push` writes into the config tree's
+ * `functions/` directory (#3182). A tree that has pushed once therefore types
+ * `ctx.db` against its own schemas; one that has not gets the open form and
+ * still compiles.
+ */
+export interface DatabaseSchemas {}
+
+/**
+ * The type keys `ctx.db` accepts.
+ *
+ * Every key the augmentation declares, and NOTHING else, once a tree has
+ * pushed: naming a type the app does not have is a compile error. Before that
+ * — an unaugmented tree, a function written before the first push —
+ * `DatabaseSchemas` is empty and `keyof` it is `never`, which would make the
+ * argument unwritable rather than open. So the empty case widens to `string`
+ * and the handle is untyped instead of unusable.
+ */
+export type DatabaseTypeKeys = [keyof DatabaseSchemas] extends [never]
+  ? string
+  : keyof DatabaseSchemas & string;
+
+/** A model's row shape, or an open record for a type with no schema. */
+export type DatabaseModels<K extends string> = K extends keyof DatabaseSchemas
+  ? DatabaseSchemas[K]
+  : Record<string, Record<string, unknown>>;
+
+/**
+ * The model names one database type addresses — its own, or any name at all
+ * for a type that declares no schema (the DO is schemaless, so a grant on such
+ * a type is legal and there is simply nothing to narrow to).
+ */
+export type DatabaseModelNames<TModels> = [keyof TModels] extends [never]
+  ? string
+  : keyof TModels & 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>;
+
+/**
+ * One model of one database, scoped: the `modelName` every records call needs
+ * is bound once, so a call names an operation and its own arguments.
+ *
+ * Filters and options are ordinary objects. Inline filter typing arrives with
+ * unified schemas — the intent's decision, not an omission — so what is typed
+ * today is the model name and the row shape a read hands back.
+ */
+export type ModelScopedBody<TBody = Record<string, unknown>> = TBody & {
+  /**
+   * Bound by the handle. Reserved so a body cannot look like a second way to
+   * choose a model: the runtime assigns the handle's own model last, and a row
+   * type that said otherwise would be a lie about what came back.
+   */
+  modelName?: never;
+};
+
+/**
+ * One write inside a model-scoped batch. Every batch verb is a write, so a
+ * batch on a model needs that model's write grant whatever the ops are.
+ */
+export type ModelBatchOperation<TRow> = {
+  op: "save" | "patch" | "delete" | "increment" | "addToSet" | "removeFromSet";
+  id?: string;
+  data?: Partial<TRow>;
+  /** Bound by the handle, for the same reason every other call's is. */
+  modelName?: never;
+  [key: string]: unknown;
+};
+
+export interface DatabaseModelHandle<TRow> {
+  query(body?: ModelScopedBody): Promise<{ data: TRow[]; hasMore?: boolean; nextCursor?: string }>;
+  count(body?: ModelScopedBody): Promise<any>;
+  aggregate(body: ModelScopedBody): Promise<any>;
+  save(body: ModelScopedBody<{ id?: string; data: Partial<TRow>; [key: string]: unknown }>): Promise<any>;
+  /** Several writes to THIS model in one request; the binding is per item. */
+  batch(body: {
+    operations: Array<ModelBatchOperation<TRow>>;
+    atomic?: boolean;
+  }): Promise<any>;
+}
+
+/** One database, typed by the database TYPE key its grant names. */
+export interface DatabaseHandle<TModels> {
+  /** The database this handle addresses — part of every query cache key. */
+  databaseId: string;
+  /** The type key this handle was opened with. */
+  databaseType: string;
+  model<M extends DatabaseModelNames<TModels>>(
+    modelName: M
+  ): DatabaseModelHandle<DatabaseModelRow<TModels, M>>;
+  /**
+   * A batch may also SPAN models, and then it names each one itself — the
+   * model-scoped form above is the typed way to write the common case.
+   */
+  batch(body: {
+    operations: Array<Record<string, unknown>>;
+    atomic?: boolean;
+  }): Promise<any>;
+  /** Run one of the database type's prepared operations under this function's grants. */
+  runOperation(name: string, params?: Record<string, unknown>): Promise<any>;
+}
+
+/**
+ * One call through a granted integration — #3183.
+ *
+ * `path` is RELATIVE to the integration's `baseUrl`, and the host is the
+ * integration's: the platform resolves and normalizes the path before checking
+ * it against `allowedPaths`, so a protocol-relative path or a `..` segment is
+ * refused rather than silently sending the request somewhere else.
+ */
+export interface IntegrationCallRequest {
+  /** Must be in the integration's `allowedMethods`. Defaults to its own default. */
+  method?: string;
+  /** Relative to the integration's `baseUrl`. */
+  path?: string;
+  query?: Record<string, unknown>;
+  headers?: Record<string, string>;
+  body?: unknown;
+  /** form-urlencoded body; not combinable with `body`. */
+  form?: Record<string, unknown>;
+  bodyMode?: "json" | "raw" | "multipart";
+}
+
+/** What the upstream answered, as the platform saw it. */
+export interface IntegrationCallResult {
+  status: number;
+  headers: Record<string, string>;
+  body: unknown;
+  durationMs: number;
+  traceId: string;
+  /** Set when the platform or the upstream refused; absent on success. */
+  errorCode?: string;
+}
+
+/** What a prompt run is given — the member execute route's own body. */
+export interface PromptRunArgs {
+  variables?: Record<string, unknown>;
+  /** Run against a different model for this call only. */
+  modelOverride?: string;
+  /** Pin a specific config OF THIS PROMPT; defaults to its active one. */
+  configId?: string;
+}
+
+/** The member execute envelope, unchanged on the function path. */
+export interface PromptRunResult {
+  success: boolean;
+  output: string;
+  error?: string | null;
+  metrics?: Record<string, unknown>;
+  configId: string;
+}
+
+/** What a send delivered to. */
+export interface SendResult {
+  /** Unique live connections the frame was sent to. Zero is a success. */
+  connections: number;
+  /** True when the per-user connection ceiling stopped the fanout. */
+  truncated: boolean;
 }
 
 export interface FunctionContext {
   user: FunctionUser;
   trigger: FunctionTrigger;
   api: FunctionApi;
+  /**
+   * A typed handle over one database. The second argument is the database TYPE
+   * key — the same key a `database:<type>/<model>:read|write` grant names —
+   * and it is what selects the models this handle knows (#3182).
+   */
+  db<K extends DatabaseTypeKeys>(
+    databaseId: string,
+    databaseType: K
+  ): DatabaseHandle<DatabaseModels<K>>;
+  /**
+   * Outbound HTTP, through a granted integration and nowhere else (#3183).
+   *
+   * A function has no raw network access: every `fetch` to a host that is not
+   * the platform answers `FUNCTION_EGRESS_DENIED`, grant or no grant. What an
+   * `integration:<key>` grant buys is this call, which the MAIN WORKER makes on
+   * the function's behalf — which is why the integration's `{{secrets.*}}`
+   * credentials can be injected into the request without ever being visible to
+   * the code that asked for it.
+   */
+  integrations: {
+    call(
+      integrationKey: string,
+      request?: IntegrationCallRequest
+    ): Promise<IntegrationCallResult>;
+  };
+  /**
+   * Run one of the app's prompts, under a `prompt:<key>` grant (#3183).
+   *
+   * 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.
+   */
+  prompts: {
+    run(promptKey: string, args?: PromptRunArgs): Promise<PromptRunResult>;
+  };
+  /**
+   * The value of one app secret, under a `secret:<NAME>` grant (#3183).
+   *
+   * Prefer `ctx.integrations.call` when the secret is a credential FOR an
+   * integration: there the value is injected by the platform and never enters
+   * the sandbox at all. This is for the cases an integration cannot express.
+   *
+   * Rejects with `FUNCTION_SECRET_NOT_FOUND` when the grant names a value
+   * this environment has not been given — secrets are provisioned per
+   * environment, out of band from the push.
+   */
+  secret(name: string): Promise<string>;
+  /** The value of one app config var, under a `var:<NAME>` grant (#3183). */
+  configVar(name: string): Promise<string>;
+  /**
+   * Realtime messages to this app's clients, under a `users:send` grant
+   * (#3183).
+   *
+   * The recipient's client receives a `direct.message` frame carrying this
+   * payload and the sending function's key. Presence is not guaranteed: a
+   * member with no live socket answers `{ connections: 0 }` rather than an
+   * error.
+   */
+  users: {
+    send(userId: string, payload: unknown): Promise<SendResult>;
+  };
+  /** The same frame to ONE connection, under a `connections:send` grant. */
+  connections: {
+    send(connectionId: string, payload: unknown): Promise<SendResult>;
+  };
+}
+
+/**
+ * The durable step handle — Cloudflare Workflows' `WorkflowStep`, forwarded
+ * untouched, so `step.do` results are memoized 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`.
+ */
+export interface FunctionStep {
+  do<T>(name: string, body: () => T | Promise<T>): Promise<T>;
+  do<T>(
+    name: string,
+    config: Record<string, unknown>,
+    body: () => T | Promise<T>
+  ): Promise<T>;
+  sleep(name: string, duration: number | string): Promise<void>;
+  sleepUntil(name: string, timestamp: Date | number): Promise<void>;
+  waitForEvent<T = unknown>(
+    name: string,
+    options: Record<string, unknown>
+  ): Promise<T>;
 }
 
 export declare const SDK_STUB_VERSION: string;
@@ -692,15 +1465,143 @@ export declare const SDK_STUB_VERSION: string;
  * Declare a server function's handler.
  *
  * Both authoring styles reach the platform bootstrap identically — a plain
- * default export taking `(input, ctx)` runs exactly as a wrapped one does —
- * so this is a typing and intent marker, not a different calling convention.
+ * default export taking `(input, ctx, step)` runs exactly as a wrapped one
+ * does — so this is a typing and intent marker, not a different calling
+ * convention.
+ *
+ * `step` is the third argument in BOTH modes (#3186). A durable run gets the
+ * engine's live `WorkflowStep`; a synchronous one gets a passthrough shim
+ * (`do` runs the body, `sleep` resolves at once, `waitForEvent` throws a
+ * named error), so a durable-authored body can be exercised synchronously.
  */
 export declare function defineFunction<TInput = unknown, TOutput = unknown>(
-  handler: (input: TInput, ctx: FunctionContext) => TOutput | Promise<TOutput>
-): (input: TInput, ctx: FunctionContext) => Promise<TOutput>;
+  handler: (
+    input: TInput,
+    ctx: FunctionContext,
+    step: FunctionStep
+  ) => TOutput | Promise<TOutput>
+): (
+  input: TInput,
+  ctx: FunctionContext,
+  step: FunctionStep
+) => Promise<TOutput>;
+
+/**
+ * One declared parameter of a registered query.
+ *
+ * `caller: true` (or `type: "$caller"`) is the intent's IMMUTABLE binding:
+ * the platform injects the invocation's user and refuses a call that supplies
+ * the parameter itself.
+ */
+export interface QueryParamSpec {
+  type?: "string" | "number" | "boolean" | "any" | "$caller";
+  caller?: boolean;
+  optional?: boolean;
+  default?: unknown;
+}
+
+export interface QueryDefinition<TDb, TParams, TResult> {
+  /** The models this query touches. Caching is off unless the run matches. */
+  models: string[];
+  params?: Record<string, QueryParamSpec>;
+  /**
+   * Cache the answer for `ttlMs` — capped by the platform, and applied ONLY
+   * when the run is verified: every model the body touched was declared, and
+   * no prepared operation was used. A write through the handle drops the
+   * entries that read the written model.
+   */
+  cache?: { ttlMs: number };
+  run: (db: TDb, params: TParams) => TResult | Promise<TResult>;
+}
+
+/**
+ * Register a named query over a database handle (#3187).
+ *
+ * A registration helper, not a language: `run` is ordinary code over the same
+ * typed handle, and what registration adds is a name, declared parameters
+ * (validated, coerced and defaulted), the `$caller` binding, and a cache the
+ * platform may use when it can verify what the run touched.
+ *
+ * Register at MODULE scope: a registration made inside the handler still works
+ * for direct calls but is invisible to `config push`'s manifest.
+ */
+export declare function defineQuery<
+  TDb = DatabaseHandle<any>,
+  TParams = Record<string, any>,
+  TResult = any
+>(
+  name: string,
+  definition: QueryDefinition<TDb, TParams, TResult>
+): (db: TDb, params?: Record<string, unknown>) => Promise<TResult>;
+
+/** The same, for a registration that writes. A mutation is never cached. */
+export declare function defineMutation<
+  TDb = DatabaseHandle<any>,
+  TParams = Record<string, any>,
+  TResult = any
+>(
+  name: string,
+  definition: QueryDefinition<TDb, TParams, TResult>
+): (db: TDb, params?: Record<string, unknown>) => Promise<TResult>;
+
+/** The platform's cap on a registered query's cache TTL, in milliseconds. */
+export declare const MAX_QUERY_CACHE_TTL_MS: number;
+
+/**
+ * Map over items with BOUNDED concurrency (#3187). Results come back in the
+ * input's order; the first rejection wins and nothing new is started after it.
+ *
+ * The bound matters inside a sandbox: an unbounded fan-out over a page of rows
+ * spends the whole subrequest ceiling in one line.
+ */
+export declare function pMap<T, R>(
+  items: Iterable<T>,
+  mapper: (item: T, index: number) => R | Promise<R>,
+  options?: { concurrency?: number }
+): Promise<R[]>;
+
+/** The default concurrency `pMap` applies when none is given. */
+export declare const PMAP_DEFAULT_CONCURRENCY: number;
+
+/**
+ * A time-ordered ULID.
+ *
+ * GENERATE IT INSIDE `step.do`. A durable run re-executes its handler on
+ * every resume and memoizes only what a step returned, so an id minted at the
+ * top of a handler is a different id after a sleep — and whatever it was
+ * written into is orphaned.
+ */
+export declare function ulid(): string;
+
+/** One family's durable `step.do` configuration. */
+export interface StepPolicy {
+  retries: { limit: number; delay: string; backoff: string };
+  timeout: string;
+}
+
+/**
+ * The per-family step policies the DSL runners use, generated from their own
+ * timeout module (#3187):
+ *
+ *   await step.do("send-receipt", stepPolicy.email, () =>
+ *     ctx.api.email.send({ body: { to, subject, htmlBody } }));
+ *
+ * `retries: 0` on email and the AI families is deliberate — a retried timeout
+ * would send the same email twice or bill the same generation twice.
+ */
+export declare const stepPolicy: {
+  email: StepPolicy;
+  llm: StepPolicy;
+  gemini: StepPolicy;
+  database: StepPolicy;
+};
 
 declare const _default: {
   SDK_STUB_VERSION: string;
   defineFunction: typeof defineFunction;
+  defineQuery: typeof defineQuery;
+  defineMutation: typeof defineMutation;
+  pMap: typeof pMap;
+  ulid: typeof ulid;
 };
 export default _default;

package/index.js

@@ -31,4 +31,60 @@ export function defineFunction() {
   throw new Error(NOT_PROVIDED);
 }
 
-export default { SDK_STUB_VERSION, defineFunction };
+/**
+ * The platform's cap on a registered query's cache TTL. The stub carries the
+ * value rather than throwing, because it is a constant an author may read at
+ * module scope while type-checking outside a sandbox.
+ */
+export const MAX_QUERY_CACHE_TTL_MS = 60000;
+
+/**
+ * Register a named query or mutation (#3187). Same reason as above: an ESM
+ * named import of an export a module does not have is a LINK error, so the
+ * stub must declare every export the platform copy has — and refuse.
+ */
+export function defineQuery() {
+  throw new Error(NOT_PROVIDED);
+}
+
+export function defineMutation() {
+  throw new Error(NOT_PROVIDED);
+}
+
+/** Bounded-concurrency map. The platform copy implements it; this refuses. */
+export function pMap() {
+  throw new Error(NOT_PROVIDED);
+}
+
+/** A time-ordered ULID, minted by the platform copy. */
+export function ulid() {
+  throw new Error(NOT_PROVIDED);
+}
+
+/**
+ * The per-family durable step policies. The stub carries an empty shape rather
+ * than throwing: it is read at module scope by code that only type-checks.
+ */
+export const PMAP_DEFAULT_CONCURRENCY = 8;
+
+/**
+ * The per-family durable step policies. The stub carries the SHAPE and empty
+ * values: an author may read `stepPolicy.email` at module scope while
+ * type-checking outside a sandbox, and throwing there would break a build that
+ * never runs a function. The platform copy carries the runners' real numbers.
+ */
+export const stepPolicy = {
+  email: null,
+  llm: null,
+  gemini: null,
+  database: null,
+};
+
+export default {
+  SDK_STUB_VERSION,
+  defineFunction,
+  defineQuery,
+  defineMutation,
+  pMap,
+  ulid,
+};

package/package.json

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