@xcitedbs/client 0.3.11 → 0.3.12

package/README.md

@@ -67,6 +67,85 @@ Call **`POST /api/v1/test/sessions`** with your normal API key or Bearer (same p
 
 Tear down with **`destroyTestSession()`** (or **`DELETE /api/v1/test/sessions/current`** with the session header). With the **same** API key / Bearer and **no** `X-Test-Session`, use **`listTestSessions()`**, **`destroyAllTestSessions()`**, and **`destroyTestSessionByToken(token)`** to clear leaked sessions before large suites (avoids the default per-credential concurrent cap). See **`llms.txt`** / **`llms-full.txt`** in this package for full behavior, limits, and auth notes.
 
+## Gotchas and conventions
+
+These trip up most first-time users; they're listed once here so you don't hit them twice.
+
+### Search (`search`) tokenizes on hyphens
+
+The full-text index treats `-` as a token boundary, so `client.search({ query: 'Test - Article' })` won't match a document titled exactly `"Test - Article"` — it tokenizes to `Test`, `Article` and ranks any doc containing both. Use `search` only for relevance queries.
+
+For exact-title or exact-meta lookups, use **`unquery`** with a meta-equality filter:
+
+```ts
+client.unquery(
+  { match_start: '/spaces/<u>/docs/' },
+  [{ title: 'title', match: '$equals(title, $string("Test - Article"))' }]
+);
+```
+
+### `list*` methods return wrapper objects, not bare arrays
+
+For consistency, every `list*` family method returns an object with the data nested under a named key:
+
+| Method | Wrapper shape |
+|---|---|
+| `listIdentifiers` | `{ identifiers: string[], total, offset, limit }` |
+| `listCheckpoints` | `{ checkpoints: CheckpointRecord[], total, branch }` |
+| `listUserWorkspaces` | `{ user_workspaces: [...] }` |
+| `listBookmarks` | `{ bookmarks: [...], total }` |
+
+Don't `for…of` the result directly — use `for (const x of ids.identifiers)`, not `for (const x of ids)`.
+
+### Reading meta — `getMeta` and `queryMeta`
+
+The read sibling of `addMeta` / `appendMeta` / `clearMeta` is **`getMeta`** (alias of `queryMeta`). With an empty `path` it returns the whole top-level meta object, which by convention is keyed by tool/flow:
+
+```ts
+const meta = await client.getMeta(docId);            // { lint: {...}, summary: {...}, ... }
+const lint = await client.getMeta(docId, 'lint');    // just the lint sub-object
+```
+
+For an array-typed or keyed-object meta path (e.g. an items list, or a per-tool dictionary), pair with **`appendItem`** to push and **`removeItem`** to atomically delete by key — `removeItem` matches against `id` / `item_id` (or by string equality for primitive arrays) and writes back inside one server-side write txn, avoiding the read/modify/write race that read-then-set on the client would create.
+
+### Overlay test sessions — visibility matrix
+
+`createTestSession({ overlay: true })` lets you read production data and write into an isolated overlay. The visibility model is **not "read-through everywhere"** — these are the layers that participate in the overlay→base fallback:
+
+| API | Sees prod data? |
+|---|---|
+| Document and meta reads (anywhere in the doc store) | **yes** |
+| Branch table existence checks (e.g. `_uw/<owner>/<slug>`) | **yes** |
+| Per-branch identifier scans on base-only branches (`listIdentifiers`, `compare`) | **yes** |
+| User-workspace records (`listUserWorkspaces`, `getUserWorkspace`) | **yes** |
+| Branch tip / commit lookups (`listCheckpoints`, `compare` against checkpoints) | **yes** |
+| `publishUserWorkspace` writes | sandboxed in overlay — does **not** touch prod |
+| `createCheckpoint`, `addMeta`, `addDocument`, etc. | sandboxed in overlay |
+
+Anything you write inside an overlay session lives under `_test/<uuid>/` and is dropped when the session is destroyed. To inspect a real production conflict mutation-free, call the production admin client directly with `{ autoResolve: 'none' }`.
+
+### `compare()` ref shapes
+
+`{ branch }` without `date` or `checkpoint_id` resolves to the branch's **live tip**, not its base. On a branch with zero checkpoints the server returns 400 `branch_has_no_commits` rather than producing an ambiguous diff — pass an explicit `date` or `checkpoint_id` instead.
+
+`compare()` accepts **both** `matchStart` (camelCase, our convention) and `match_start` (snake_case, matching `XCiteQuery`) on the options object; they're equivalent.
+
+### `withContext` / `fork`
+
+`fork(partial)` returns a child client with the merged context (workspace, date, prefix). **`withContext(partial)`** is a one-line alias for the same operation.
+
+### `_xcite_json_doc` sentinel
+
+JSON documents written via `writeJsonDocument` no longer leak the internal `_xcite_json_doc: true` marker into the read payload — the server strips it before serializing. Older clients that filtered it out can drop that workaround. Likewise, `deleteDocument` now correctly removes JSON documents (it routes JSON ids through `deleteJSON` automatically); you don't need to pick `deleteJsonDocument` based on the document's storage shape.
+
+### `testAuth: 'bypass'` requires the creator credential
+
+When you create a test session, the issuing API key/Bearer is the **creator credential**. Calling endpoints under `X-Test-Auth: bypass` requires presenting that same credential alongside `X-Test-Session`; it isn't only a login restriction. If you can't present the creator credential (e.g. you're operating from a different identity), switch to `X-Test-Auth: required` and the session itself authenticates the request.
+
+### BFF/SPA-side concerns (tracked separately)
+
+The following are app/BFF-repo concerns rather than SDK or server bugs: `getOrCreateDraft` check-then-act races (TOCTOU on per-`(user, key)` resource minting); coexisting legacy and modern `last-drafts` storage formats with different identifier encodings; and project-level workspace wiring of `@xcitedbs/client` for top-level diagnostic scripts. They're tracked in the BFF/SPA repo and aren't fixed here.
+
 ## Build
 
 ```bash

package/dist/client.d.ts

@@ -1,4 +1,4 @@
-import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, TriggerEventsResponse, StoredPolicyResponse, TxnRequest, TxnResponse, VerifyAppUserTokenOptions, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult, UserIsolationShareListResponse, UserIsolationUnshareParams, ShareDirection, AppUserGroup, CreateGroupParams, ListGroupsResponse } from './types';
+import { AccessCheckResult, AppAuthConfig, AppEmailConfig, AppEmailTemplates, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BranchInfo, BookmarkRecord, CheckpointRecord, CommitRecord, CompareRef, CompareResult, DatabaseContext, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, DocumentBatchResponse, DocumentExportFormat, ExportDocumentResult, Flags, JsonDocumentBatchItem, ImportDocumentOptions, ImportDocumentResult, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LogEntry, MergeResult, PublishResult, RebaseUserWorkspaceResult, WorkspaceInfo, MetaValue, PlatformRegisterResult, PolicySubjectInput, UnqueryResult, UnqueryTemplate, PolicyUpdateResponse, RealtimeEvent, SecurityConfig, SecurityPolicy, StoredTriggerResponse, TriggerDefinition, TriggerEventsResponse, StoredPolicyResponse, TxnRequest, TxnResponse, VerifyAppUserTokenOptions, SubscriptionOptions, TagRecord, TextSearchQuery, TextSearchResult, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkResult, AssetShareListResponse, AssetShareRequest, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, VectorIndexEstimate, RagQueryOptions, RagQueryResult, RagStreamEvent, OAuthProvidersResponse, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspacesResponse, TokenPair, UserInfo, ApiKeyInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateTestSessionOptions, XCiteDBClientOptions, XCiteDBJwtClaims, TestSessionBootstrapSummary, TestSessionInfo, XCiteQuery, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationShareResult, UserIsolationShareListResponse, UserIsolationUnshareParams, ShareDirection, AppUserGroup, CreateGroupParams, ListGroupsResponse, FunctionManifest, FunctionListItem, FunctionDeployRequest, FunctionSecretsList } from './types';
 import { WebSocketSubscription } from './websocket';
 export declare class XCiteDBClient {
     private baseUrl;
@@ -217,6 +217,8 @@ export declare class XCiteDBClient {
      * the `onSessionTokensUpdated` / `onAppUserTokensUpdated` callbacks supplied at construction.
      */
     fork(partial?: Partial<DatabaseContext>): XCiteDBClient;
+    /** Alias for {@link fork}. Both names are commonly guessed; this avoids a discoverability cliff. */
+    withContext(partial?: Partial<DatabaseContext>): XCiteDBClient;
     setTokens(access: string, refresh?: string): void;
     /** End-user (app) tokens. With developer `accessToken`/`apiKey`, sent as `X-App-User-Token`. */
     setAppUserTokens(access: string, refresh?: string): void;
@@ -454,6 +456,56 @@ export declare class XCiteDBClient {
      * `admin`/`editor` roles can read this; public-key requests are rejected.
      */
     listTriggerEvents(limit?: number): Promise<TriggerEventsResponse>;
+    /**
+     * List deployed functions for the current project. Returns metadata only
+     * (no wasm bytes). Requires admin or editor role on the project.
+     */
+    listFunctions(): Promise<FunctionListItem[]>;
+    /**
+     * Fetch a single function's manifest. Wasm bytes are omitted unless
+     * `includeWasm` is true (admin export path).
+     */
+    getFunction(name: string, opts?: {
+        includeWasm?: boolean;
+    }): Promise<FunctionManifest>;
+    /**
+     * Deploy / replace a function. Body MUST include `wasm_b64` (base64 wasm
+     * bytes) plus the manifest fields. Server validates the wasm magic and
+     * compiles it before persisting.
+     */
+    deployFunction(name: string, manifest: FunctionDeployRequest): Promise<FunctionManifest>;
+    deleteFunction(name: string): Promise<{
+        deleted: string;
+    }>;
+    invokeFunction<T = unknown>(name: string, body?: unknown): Promise<T>;
+    /**
+     * List the secret-name slots for a function. Each entry carries `set:
+     * true|false` — values are NEVER returned. The `orphan_secrets` field, if
+     * present, lists names that were once set but no longer appear in the
+     * manifest's `secrets[]` declaration; clean up via deleteFunctionSecret.
+     * Requires admin role.
+     */
+    listFunctionSecrets(name: string): Promise<FunctionSecretsList>;
+    /**
+     * Set one or more secret values. Each KEY must be declared in the
+     * manifest's `secrets[]` array; values are encrypted at rest and never
+     * round-trip on any GET. Requires admin role.
+     *
+     * @example
+     * ```ts
+     * await client.setFunctionSecrets('charge', {
+     *   STRIPE_KEY: 'sk_live_...',
+     *   WEBHOOK_SIGNING_KEY: 'whsec_...',
+     * });
+     * ```
+     */
+    setFunctionSecrets(name: string, values: Record<string, string>): Promise<{
+        function: string;
+        set: string[];
+    }>;
+    deleteFunctionSecret(name: string, key: string): Promise<{
+        deleted: string;
+    }>;
     /**
      * Dry-run access check (`POST /api/v1/security/check`). Returns `effect` and optional `matched_policy_id`.
      * Useful for debugging policies. Actions: `read`, `write`, `delete`, `list`, `unquery`.
@@ -673,12 +725,14 @@ export declare class XCiteDBClient {
     compare(from: CompareRef, to: CompareRef, options?: {
         includeContent?: boolean;
         matchStart?: string;
+        match_start?: string;
     }): Promise<CompareResult>;
     /** @deprecated Use {@link compare}. */
     diff(from: DiffRef, to: DiffRef, includeContent?: boolean): Promise<DiffResult>;
     diff(from: DiffRef, to: DiffRef, options?: {
         includeContent?: boolean;
         matchStart?: string;
+        match_start?: string;
     }): Promise<DiffResult>;
     /**
      * Compare two XML provision trees structurally + textually and write the resulting
@@ -889,6 +943,20 @@ export declare class XCiteDBClient {
         overwrite?: boolean;
         context?: Partial<DatabaseContext>;
     }): Promise<boolean>;
+    /**
+     * Atomic single-item removal — sibling to {@link appendItem}. Resolves to true when
+     * the item was found and removed, false (HTTP 404) when no match. Behavior depends on
+     * the meta shape at `path`:
+     *   - object → drops the field named `itemKey` (siblings untouched).
+     *   - array  → drops entries equal to `itemKey` (string), or whose `id`/`item_id`
+     *     matches `itemKey`.
+     * Read+filter+write happens server-side inside one write txn so concurrent removes
+     * on the same key elect exactly one winner — use this instead of read-then-set on the
+     * client to avoid the race-loser cleanup the convention warns about.
+     */
+    removeItem(identifier: string, itemKey: string, path?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<boolean>;
     /** Convenience: push a single item via query. Wraps `item` in `[item]` and calls {@link appendMetaByQuery}. */
     appendItemByQuery<T = unknown>(query: XCiteQuery, item: T, path?: string, firstMatch?: boolean, opts?: {
         overwrite?: boolean;
@@ -897,6 +965,14 @@ export declare class XCiteDBClient {
     queryMeta<T = MetaValue>(identifier: string, path?: string, opts?: {
         context?: Partial<DatabaseContext>;
     }): Promise<T>;
+    /**
+     * Alias for {@link queryMeta} that pairs by name with {@link addMeta} / {@link appendMeta} /
+     * {@link clearMeta}. With `path` empty this returns the whole top-level meta object — which
+     * by convention is keyed per tool/flow.
+     */
+    getMeta<T = MetaValue>(identifier: string, path?: string, opts?: {
+        context?: Partial<DatabaseContext>;
+    }): Promise<T>;
     queryMetaByQuery<T = MetaValue>(query: XCiteQuery, path?: string, opts?: {
         context?: Partial<DatabaseContext>;
     }): Promise<T>;

package/dist/client.js

@@ -894,6 +894,10 @@ class XCiteDBClient {
         child.cachedAppUserId = undefined;
         return child;
     }
+    /** Alias for {@link fork}. Both names are commonly guessed; this avoids a discoverability cliff. */
+    withContext(partial) {
+        return this.fork(partial);
+    }
     setTokens(access, refresh) {
         this.accessToken = access;
         if (refresh !== undefined)
@@ -1606,6 +1610,72 @@ class XCiteDBClient {
             limit: typeof r?.limit === 'number' ? r.limit : 0,
         };
     }
+    // ----- Functions / BFF (Phase 2 + 2.5 + 9) -----
+    // Server-side WASM functions stored at /_xcitedb/functions/<name> per
+    // tenant. Manifests carry runtime, identity_mode, limits, env (non-secret
+    // config), egress_allowlist, secrets[] (capability declaration), and the
+    // raw wasm bytes (base64). Secret VALUES live in a separate per-function
+    // store and are never returned by any GET path — only set via PUT and
+    // observed as `set: true|false` via list.
+    /**
+     * List deployed functions for the current project. Returns metadata only
+     * (no wasm bytes). Requires admin or editor role on the project.
+     */
+    async listFunctions() {
+        const r = await this.request('GET', '/api/v1/functions');
+        return Array.isArray(r?.functions) ? r.functions : [];
+    }
+    /**
+     * Fetch a single function's manifest. Wasm bytes are omitted unless
+     * `includeWasm` is true (admin export path).
+     */
+    async getFunction(name, opts) {
+        const q = buildQuery({ include_wasm: opts?.includeWasm ? 'true' : undefined });
+        return this.request('GET', `/api/v1/functions/${encodeURIComponent(name)}${q}`);
+    }
+    /**
+     * Deploy / replace a function. Body MUST include `wasm_b64` (base64 wasm
+     * bytes) plus the manifest fields. Server validates the wasm magic and
+     * compiles it before persisting.
+     */
+    async deployFunction(name, manifest) {
+        return this.request('PUT', `/api/v1/functions/${encodeURIComponent(name)}`, manifest);
+    }
+    async deleteFunction(name) {
+        return this.request('DELETE', `/api/v1/functions/${encodeURIComponent(name)}`);
+    }
+    async invokeFunction(name, body) {
+        return this.request('POST', `/api/v1/functions/${encodeURIComponent(name)}/invoke`, body);
+    }
+    /**
+     * List the secret-name slots for a function. Each entry carries `set:
+     * true|false` — values are NEVER returned. The `orphan_secrets` field, if
+     * present, lists names that were once set but no longer appear in the
+     * manifest's `secrets[]` declaration; clean up via deleteFunctionSecret.
+     * Requires admin role.
+     */
+    async listFunctionSecrets(name) {
+        return this.request('GET', `/api/v1/functions/${encodeURIComponent(name)}/secrets`);
+    }
+    /**
+     * Set one or more secret values. Each KEY must be declared in the
+     * manifest's `secrets[]` array; values are encrypted at rest and never
+     * round-trip on any GET. Requires admin role.
+     *
+     * @example
+     * ```ts
+     * await client.setFunctionSecrets('charge', {
+     *   STRIPE_KEY: 'sk_live_...',
+     *   WEBHOOK_SIGNING_KEY: 'whsec_...',
+     * });
+     * ```
+     */
+    async setFunctionSecrets(name, values) {
+        return this.request('PUT', `/api/v1/functions/${encodeURIComponent(name)}/secrets`, values);
+    }
+    async deleteFunctionSecret(name, key) {
+        return this.request('DELETE', `/api/v1/functions/${encodeURIComponent(name)}/secrets/${encodeURIComponent(key)}`);
+    }
     /**
      * Dry-run access check (`POST /api/v1/security/check`). Returns `effect` and optional `matched_policy_id`.
      * Useful for debugging policies. Actions: `read`, `write`, `delete`, `list`, `unquery`.
@@ -2025,7 +2095,9 @@ class XCiteDBClient {
         }
         else if (third !== undefined && typeof third === 'object') {
             include_content = third.includeContent ?? false;
-            match_start = third.matchStart;
+            // Accept both casings: matchStart (camelCase, our convention) and match_start
+            // (snake_case, matching XCiteQuery and the wire field). camelCase wins on conflict.
+            match_start = third.matchStart ?? third.match_start;
         }
         const body = {
             from,
@@ -2478,6 +2550,33 @@ class XCiteDBClient {
     async appendItem(identifier, item, path = '', opts) {
         return this.appendMeta(identifier, [item], path, opts);
     }
+    /**
+     * Atomic single-item removal — sibling to {@link appendItem}. Resolves to true when
+     * the item was found and removed, false (HTTP 404) when no match. Behavior depends on
+     * the meta shape at `path`:
+     *   - object → drops the field named `itemKey` (siblings untouched).
+     *   - array  → drops entries equal to `itemKey` (string), or whose `id`/`item_id`
+     *     matches `itemKey`.
+     * Read+filter+write happens server-side inside one write txn so concurrent removes
+     * on the same key elect exactly one winner — use this instead of read-then-set on the
+     * client to avoid the race-loser cleanup the convention warns about.
+     */
+    async removeItem(identifier, itemKey, path = '', opts) {
+        const body = {
+            identifier: this.isoPrefixId(identifier),
+            item_key: itemKey,
+            path,
+        };
+        try {
+            const r = await this.request('DELETE', '/api/v1/meta/item', body, undefined, { contextOverride: opts?.context });
+            return r?.ok !== false;
+        }
+        catch (e) {
+            if (e instanceof types_1.XCiteDBError && e.status === 404)
+                return false;
+            throw e;
+        }
+    }
     /** Convenience: push a single item via query. Wraps `item` in `[item]` and calls {@link appendMetaByQuery}. */
     async appendItemByQuery(query, item, path = '', firstMatch = false, opts) {
         return this.appendMetaByQuery(query, [item], path, firstMatch, opts);
@@ -2485,6 +2584,14 @@ class XCiteDBClient {
     async queryMeta(identifier, path = '', opts) {
         return this.request('GET', `/api/v1/meta${buildQuery({ identifier: this.isoPrefixId(identifier), path })}`, undefined, undefined, { contextOverride: opts?.context });
     }
+    /**
+     * Alias for {@link queryMeta} that pairs by name with {@link addMeta} / {@link appendMeta} /
+     * {@link clearMeta}. With `path` empty this returns the whole top-level meta object — which
+     * by convention is keyed per tool/flow.
+     */
+    async getMeta(identifier, path = '', opts) {
+        return this.queryMeta(identifier, path, opts);
+    }
     async queryMetaByQuery(query, path = '', opts) {
         return this.request('POST', '/api/v1/meta/query', { query: this.isoPrefixQuery(query), path }, undefined, { contextOverride: opts?.context });
     }

package/dist/index.d.ts

@@ -1,5 +1,5 @@
 export { XCiteDBClient } from './client';
 export { parseAssetUri, formatAssetUri, collectIdentifiersFromText, ASSET_URI_PREFIX } from './assetUri';
 export { WebSocketSubscription } from './websocket';
-export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, SmartDiffStats, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SandboxApiKeyMintResult, SandboxInfo, SandboxMember, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TriggerEvent, TriggerEventsResponse, TxnOperation, TxnOperationResult, TxnPrecondition, TxnPreconditionResult, TxnRequest, TxnResponse, JwksKey, JwksResponse, VerifyAppUserTokenOptions, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, UserIsolationShareListEntry, UserIsolationShareListResponse, UserIsolationUnshareParams, ShareTarget, ShareDirection, AppUserGroup, AppUserGroupKind, CreateGroupParams, ListGroupsResponse, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateSandboxOptions, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
+export type { AccessCheckResult, ApiKeyInfo, AppAuthConfig, AppEmailConfig, AppEmailSmtpConfig, AppEmailTemplateEntry, AppEmailTemplates, AppEmailWebhookConfig, AppUser, AppUserTokenPair, EmailTestResponse, ForgotPasswordResponse, SendVerificationResponse, BookmarkRecord, BranchInfo, BranchListItem, CheckpointRecord, CommitRecord, CompareEntry, CompareRef, CompareResult, DatabaseContext, DiffEntry, DiffRef, DiffResult, SmartDiffRef, SmartDiffResult, SmartDiffStats, DocumentBatchResponse, DocumentBatchResultRow, DocumentExportFormat, DocumentImportFormat, ExportDocumentResult, Flags, ImportDocumentOptions, ImportDocumentResult, JsonDocumentData, JsonDocumentBatchItem, IdentifierChildNode, ListIdentifierChildrenResult, ListIdentifiersResult, LockInfo, AcquireLockOptions, LockConflictBody, LockExpiredBody, LockUnknownBody, MergeConflict, MergeResult, OAuthProviderInfo, OAuthProvidersResponse, OwnedTenantInfo, ProjectInfo, PlatformRegistrationConfig, PlatformWorkspaceOrg, PlatformWorkspacesResponse, ProjectSearchSettings, ProjectSearchSettingsUpdate, ProjectDocConfResponse, AssetGcDryRunResult, AssetHeadResult, AssetListItem, AssetListResponse, AssetMagicLinkListResponse, AssetMagicLinkRecord, AssetMagicLinkResult, AssetShareListEntry, AssetShareListResponse, AssetShareRequest, AssetStorageImport, AssetStorageMount, AssetStorageTarget, AssetStorageTargetType, AssetUnshareRequest, AssetUploadResult, CreateAssetMagicLinkRequest, ListAssetsOptions, ProjectAssetStorageConfig, UploadAssetOptions, PlatformDefaultDocConfResponse, LogEntry, MetaValue, PlatformRegisterResult, PolicyUpdateResponse, PublishConflict, PublishResult, RebaseUserWorkspaceResult, PolicyConditions, PolicyIdentifierPattern, PolicyResources, PolicySubjectInput, PolicySubjects, RagQueryOptions, RagQueryResult, RagStreamEvent, RealtimeEvent, SandboxApiKeyMintResult, SandboxInfo, SandboxMember, SearchIndexingProgress, SecurityConfig, SecurityPolicy, StoredPolicyResponse, StoredTriggerResponse, SubscriptionOptions, TagRecord, TextSearchHit, TextSearchQuery, TextSearchResult, TriggerDefinition, TriggerEvent, TriggerEventsResponse, FunctionManifest, FunctionListItem, FunctionDeployRequest, FunctionLimits, FunctionSecretEntry, FunctionSecretsList, TxnOperation, TxnOperationResult, TxnPrecondition, TxnPreconditionResult, TxnRequest, TxnResponse, JwksKey, JwksResponse, VerifyAppUserTokenOptions, TokenPair, UserInfo, UserIsolationConfig, UserIsolationCreateShareParams, UserIsolationOptions, UserIsolationShareMode, UserIsolationShareResult, UserIsolationShareListEntry, UserIsolationShareListResponse, UserIsolationUnshareParams, ShareTarget, ShareDirection, AppUserGroup, AppUserGroupKind, CreateGroupParams, ListGroupsResponse, WorkspaceInfo, WriteDocumentOptions, XmlDocumentBatchItem, CreateSandboxOptions, CreateTestSessionOptions, TestSessionBootstrap, TestSessionBootstrapSummary, TestSessionInfo, XCiteDBClientOptions, XCiteDBErrorExtras, XCiteDBJwtClaims, UnqueryResult, UnqueryTemplate, XCiteQuery, } from './types';
 export { XCiteDBError, XCiteDBForbiddenError, XCiteDBNotFoundError, XCiteDBAuthError, XCiteDBLockConflictError, } from './types';

package/dist/types.d.ts

@@ -1223,6 +1223,93 @@ export interface StoredTriggerResponse {
     trigger_id: string;
     trigger: TriggerDefinition;
 }
+export interface FunctionLimits {
+    /** Per-invocation fuel budget (0 = use server default). */
+    fuel?: number;
+    /** Per-invocation wall-clock cap in ms (0 = use server default). */
+    wall_ms?: number;
+    /** Per-invocation linear-memory cap in MiB (0 = use server default). */
+    mem_mb?: number;
+}
+/**
+ * Wire-format function manifest as surfaced by `GET /api/v1/functions/{name}`.
+ * Note: `wasm_b64` is included only when `?include_wasm=true` was requested
+ * (admin export path); the standard read path returns `wasm_size` instead.
+ * Secret VALUES are NEVER returned by any GET path — `secrets` here is the
+ * capability-list declaration (just names).
+ */
+export interface FunctionManifest {
+    name: string;
+    version: number;
+    entrypoint: string;
+    /** Phase 2.5: only `"raw_wasm"`. Phase 4 adds `"javy"` (server-compiled JS/TS). */
+    runtime: 'raw_wasm' | 'javy';
+    /** Phase 2.5: only `"as_caller"`. Phase 5 adds `"as_role"`. */
+    identity_mode: 'as_caller' | 'as_role';
+    role?: string;
+    limits: FunctionLimits;
+    /**
+     * Per-function egress allowlist applied by `xcite.fetch`. Hostnames and
+     * `*.example.com` glob patterns; empty = no external HTTP allowed.
+     */
+    egress_allowlist: string[];
+    /**
+     * Capability-style declaration of secret names this function may read at
+     * runtime. Set values via `setFunctionSecrets` — they are never echoed
+     * back. To remove a name from the function's capability set, drop it
+     * from this array on the next deploy AND call `deleteFunctionSecret` for
+     * any orphaned value.
+     */
+    secrets: string[];
+    /**
+     * Non-secret config: URLs, feature flags, model names. Round-trips on
+     * GET — DO NOT put API keys / passwords here.
+     */
+    env: Record<string, string | number | boolean | null>;
+    /** Size of the stored .wasm bytes in bytes. */
+    wasm_size?: number;
+    /** Only present when `getFunction(name, { includeWasm: true })`. */
+    wasm_b64?: string;
+}
+/** Compact metadata used by the list endpoint (`GET /api/v1/functions`). */
+export type FunctionListItem = FunctionManifest;
+/**
+ * Body for `PUT /api/v1/functions/{name}` (function deploy). The server
+ * fills `name` from the URL path; sending it in the body is ignored.
+ * Validation: `wasm_b64` is required and must decode to a wasm module
+ * starting with the magic header `\\0asm`.
+ */
+export interface FunctionDeployRequest {
+    version?: number;
+    entrypoint?: string;
+    runtime?: 'raw_wasm' | 'javy';
+    identity_mode?: 'as_caller' | 'as_role';
+    role?: string;
+    limits?: FunctionLimits;
+    egress_allowlist?: string[];
+    secrets?: string[];
+    env?: Record<string, string | number | boolean | null>;
+    /** Required: base64-encoded wasm bytes. */
+    wasm_b64: string;
+}
+export interface FunctionSecretEntry {
+    name: string;
+    /** True iff a value is currently stored. Values themselves are never returned. */
+    set: boolean;
+}
+export interface FunctionSecretsList {
+    function: string;
+    secrets: FunctionSecretEntry[];
+    /**
+     * Names that have a stored value but are no longer declared in the
+     * manifest's `secrets[]` array. Operators should either re-declare or
+     * delete each one — orphans are unreachable by guests but still take
+     * storage and audit attention.
+     */
+    orphan_secrets?: string[];
+    /** "project" | "sealed" | "none" — which encryption backend the server picked. */
+    backend: string;
+}
 /** Named snapshot on a workspace (checkpoint). */
 export interface CheckpointRecord {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xcitedbs/client",
-  "version": "0.3.11",
+  "version": "0.3.12",
   "description": "XCiteDB BaaS client SDK",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",