@seliseblocks/client 0.2.0 → 0.3.0

package/dist/data/data-client.js

@@ -289,13 +289,13 @@ export class BlocksDataClient {
              */
             create: (payload) => this.graphql({
                 operationName: createField,
-                query: `mutation ${createField}($input: ${schemaName}InsertInput!) {
-  ${createField}(input: $input) {
-    acknowledged
-    itemId
-    message
-    totalImpactedData
-  }
+                query: `mutation ${createField}($input: ${schemaName}InsertInput!) {
+  ${createField}(input: $input) {
+    acknowledged
+    itemId
+    message
+    totalImpactedData
+  }
 }`,
                 variables: { input: payload }
             }),
@@ -306,13 +306,13 @@ export class BlocksDataClient {
              */
             delete: (itemId, deleteOptions = {}) => this.graphql({
                 operationName: deleteField,
-                query: `mutation ${deleteField}($filter: String, $input: ${schemaName}DeleteInput!) {
-  ${deleteField}(filter: $filter, input: $input) {
-    acknowledged
-    itemId
-    message
-    totalImpactedData
-  }
+                query: `mutation ${deleteField}($filter: String, $input: ${schemaName}DeleteInput!) {
+  ${deleteField}(filter: $filter, input: $input) {
+    acknowledged
+    itemId
+    message
+    totalImpactedData
+  }
 }`,
                 variables: {
                     filter: itemIdFilter(itemId),
@@ -354,13 +354,13 @@ export class BlocksDataClient {
              */
             update: (itemId, payload) => this.graphql({
                 operationName: updateField,
-                query: `mutation ${updateField}($filter: String, $input: ${schemaName}UpdateInput!) {
-  ${updateField}(filter: $filter, input: $input) {
-    acknowledged
-    itemId
-    message
-    totalImpactedData
-  }
+                query: `mutation ${updateField}($filter: String, $input: ${schemaName}UpdateInput!) {
+  ${updateField}(filter: $filter, input: $input) {
+    acknowledged
+    itemId
+    message
+    totalImpactedData
+  }
 }`,
                 variables: {
                     filter: itemIdFilter(itemId),
@@ -472,18 +472,18 @@ function dynamicQueryInput(options) {
     };
 }
 function collectionListQuery(fieldName, selection) {
-    return `query ${fieldName}($input: DynamicQueryInput) {
-  ${fieldName}(input: $input) {
-    items {
-${indent(selection, 6)}
-    }
-    totalCount
-    pageNo
-    pageSize
-    totalPages
-    hasNextPage
-    hasPreviousPage
-  }
+    return `query ${fieldName}($input: DynamicQueryInput) {
+  ${fieldName}(input: $input) {
+    items {
+${indent(selection, 6)}
+    }
+    totalCount
+    pageNo
+    pageSize
+    totalPages
+    hasNextPage
+    hasPreviousPage
+  }
 }`;
 }
 function selectionFor(fields) {

package/dist/functions.d.ts

@@ -0,0 +1,135 @@
+/**
+ * Types for code that runs INSIDE a Blocks function -- the sandbox contract the runner's
+ * bootstrap hands every handler. Type-only: a function's own package.json does not need this
+ * package at runtime. Use it as a devDependency for editor completion and checking:
+ *
+ * ```js
+ * // index.js (the function's package.json declares "type": "module")
+ * /** @type {import("@seliseblocks/client/functions").FunctionHandler} *\/
+ * export default async function handler(input, ctx) {
+ *   ctx.log.info("called", { path: input.path });
+ *   return { ok: true };
+ * }
+ * ```
+ *
+ * Runtime: Node 24, ES modules. Every run gets the same fixed profile -- 100 millicores,
+ * 128 MB, 30 s wall clock, 10 concurrent runs per function, one retry after 5 s.
+ */
+/** HTTP verbs a trigger may accept. */
+export type FunctionHttpMethod = "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
+/**
+ * What an HTTP or Test invocation hands the handler. Anything after `/fn/{id}` is `path`; the
+ * body arrives parsed when it is JSON. A workflow step passes the previous step's output
+ * instead of this shape, so a handler used from both should check `input.method`.
+ */
+export interface FunctionInput {
+    /** One of the trigger's accepted methods -- any other is refused with 405 before the handler runs. */
+    readonly method: FunctionHttpMethod;
+    /** `orders/42` for a call to `…/fn/{id}/orders/42`; `""` for the root. */
+    readonly path: string;
+    /** A repeated key is an array. */
+    readonly query: Readonly<Record<string, string | string[]>>;
+    /** Lower-cased. Content negotiation, provenance and webhook signatures -- never a credential. */
+    readonly headers: Readonly<Record<string, string>>;
+    /** Parsed JSON, the raw text for other content types, null for no body (always null on GET). */
+    readonly body: unknown;
+    /**
+     * The exact request bytes, base64 -- what a webhook signature is computed over. Null with no
+     * body, or when the body is too large to carry twice.
+     */
+    readonly rawBody: string | null;
+}
+/** Who invoked this run. An empty identity on a public call -- never a privileged token. */
+export interface FunctionCallerContext {
+    readonly tenantId: string;
+    /** null when the trigger is public. */
+    readonly userId: string | null;
+    readonly roles: readonly string[];
+    readonly permissions: readonly string[];
+    readonly isAuthenticated: boolean;
+}
+/** Calling Blocks APIs as the caller. */
+export interface FunctionBlocksAccess {
+    /**
+     * A fresh, short-lived Blocks access token for the user who invoked this run -- pass it as the
+     * `Authorization: Bearer` of a Blocks API call, with `ctx.context.tenantId` as `x-blocks-key`.
+     * Fetched on demand (one IAM round trip per run; later calls in the same run get the same
+     * token). Resolves to `undefined` when there is no signed-in caller (a public trigger, a
+     * scheduled workflow) or none could be issued. Masked in logs.
+     */
+    getAccessToken(): Promise<string | undefined>;
+}
+/**
+ * The function's variables, as plain strings, snapshotted at deploy. A variable bound to a
+ * secret (`{{secret.<id>}}`) arrives as its real value and is masked in logs.
+ */
+export interface FunctionEnv {
+    readonly [key: string]: string | undefined;
+}
+/** This run's own metadata. */
+export interface FunctionRun {
+    readonly id: string;
+    /** Active version number this run executed on. */
+    readonly version: number;
+    /** 1 for the first try; 2 when the retry re-ran it. */
+    readonly attempt: number;
+    readonly invokedBy: {
+        readonly type: "http" | "workflow" | "test" | "replay";
+        /** What started the run (e.g. the workflow), or null when there is none. */
+        readonly id: string | null;
+    };
+}
+/** Structured log lines kept on the run (`blocks logic function logs <runId>`); `console` is captured too. */
+export interface FunctionLogger {
+    debug(message: string, data?: unknown): void;
+    info(message: string, data?: unknown): void;
+    warn(message: string, data?: unknown): void;
+    error(message: string, data?: unknown): void;
+}
+/**
+ * Everything the sandbox hands a function, fresh for every call.
+ *
+ * HTTP calls of a deployed function reuse a warm sandbox: module-level code runs once and its
+ * variables live on to the next call -- maybe another user's. Keep connections and caches at
+ * module level; keep request data (input, ctx, tokens) inside the handler. Await everything, or
+ * hand work that may finish after the answer to `waitUntil`.
+ */
+export interface FunctionContext {
+    readonly context: FunctionCallerContext;
+    readonly blocks: FunctionBlocksAccess;
+    readonly env: FunctionEnv;
+    readonly run: FunctionRun;
+    readonly log: FunctionLogger;
+    /**
+     * Finish work after the answer is sent: the caller gets the result at once, the promise runs
+     * on (within the time limit) and the sandbox is not reused until it settles. Use it instead of
+     * a promise you do not await -- work still running after the answer makes the sandbox be replaced.
+     */
+    waitUntil(promise: Promise<unknown>): void;
+}
+/**
+ * Return this from the handler to control the HTTP answer when the trigger's response mode is
+ * `sync`. Anything else you return is sent as 200 + JSON.
+ *
+ * - `statusCode` 200-599 (1xx is refused). 204/205/304 never carry a body.
+ * - `headers`: only content and caching headers pass (content-type, content-language,
+ *   content-disposition, cache-control, expires, last-modified, etag, vary, retry-after),
+ *   `location` on a 3xx to an http(s) or relative URL, and `x-*` (except x-forwarded-*,
+ *   x-real-ip, x-original-*, x-blocks-*). `set-cookie` is always dropped.
+ * - `body`: a string is sent as is; anything else as JSON.
+ *
+ * A failed run answers 502, a timed-out one 504 (`{ error, runId }`). A call that takes too
+ * long gets 202 + a poll token instead -- the run still finishes.
+ */
+export interface FunctionHttpResponse {
+    statusCode: number;
+    headers?: Record<string, string | string[]>;
+    body?: unknown;
+}
+/**
+ * The module's default export. `input` and `ctx` exist only inside the handler: top-level code
+ * runs once when the sandbox starts (the place for clients, caches and constants), and touching
+ * `ctx` there fails the run before the handler is called. An `async function*` handler streams
+ * each yielded piece to the caller.
+ */
+export type FunctionHandler<TResult = unknown> = (input: FunctionInput, ctx: FunctionContext) => TResult | Promise<TResult> | AsyncIterable<unknown>;

package/dist/functions.js

@@ -0,0 +1,18 @@
+/**
+ * Types for code that runs INSIDE a Blocks function -- the sandbox contract the runner's
+ * bootstrap hands every handler. Type-only: a function's own package.json does not need this
+ * package at runtime. Use it as a devDependency for editor completion and checking:
+ *
+ * ```js
+ * // index.js (the function's package.json declares "type": "module")
+ * /** @type {import("@seliseblocks/client/functions").FunctionHandler} *\/
+ * export default async function handler(input, ctx) {
+ *   ctx.log.info("called", { path: input.path });
+ *   return { ok: true };
+ * }
+ * ```
+ *
+ * Runtime: Node 24, ES modules. Every run gets the same fixed profile -- 100 millicores,
+ * 128 MB, 30 s wall clock, 10 concurrent runs per function, one retry after 5 s.
+ */
+export {};

package/dist/http/errors.js

@@ -16,8 +16,32 @@ function buildMessage(status, statusText, body) {
         const message = record.message ?? record.detail ?? record.error_description ?? record.error;
         if (typeof message === "string" && message)
             return `Blocks API ${status} ${statusText}: ${message}`;
+        // Validation bodies (ASP.NET problem details and Blocks `errors` maps) carry the reason only in
+        // `errors` / `title`; without this the message would be the bare status line.
+        const details = describeErrors(record.errors ?? record.Errors);
+        const title = typeof record.title === "string" ? record.title : "";
+        if (details)
+            return `Blocks API ${status} ${statusText}: ${details}`;
+        if (title)
+            return `Blocks API ${status} ${statusText}: ${title}`;
     }
     if (typeof body === "string" && body)
         return `Blocks API ${status} ${statusText}: ${body}`;
     return `Blocks API ${status} ${statusText}`;
 }
+const MAX_ERROR_ENTRIES = 5;
+/** `{ Field: ["a", "b"] }` or `{ Field: "a" }` → `"Field: a, b; Other: c"` (first entries only). */
+function describeErrors(errors) {
+    if (typeof errors !== "object" || !errors || Array.isArray(errors))
+        return "";
+    const parts = [];
+    for (const [field, value] of Object.entries(errors)) {
+        const texts = (Array.isArray(value) ? value : [value]).filter((text) => typeof text === "string" && text.length > 0);
+        if (texts.length === 0)
+            continue;
+        parts.push(field ? `${field}: ${texts.join(", ")}` : texts.join(", "));
+        if (parts.length === MAX_ERROR_ENTRIES)
+            break;
+    }
+    return parts.join("; ");
+}

package/dist/http/http-client.d.ts

@@ -7,5 +7,16 @@ export declare class BlocksHttpClient {
     private readonly fetchImpl;
     constructor(config: BlocksResolvedConfig, auth: BlocksAuthenticationClient, fetchImpl?: typeof fetch);
     request<T>(path: string, options?: BlocksRequestOptions): Promise<T>;
+    /**
+     * What: sends a Blocks API request and returns the raw `Response`, unread.
+     * Why: some answers carry meaning in the status and headers rather than only the
+     * body -- a function invocation's 202 vs. its synchronous answer, `Retry-After`,
+     * a streamed body -- which `request` reduces to parsed JSON.
+     * How: same credentials, `x-blocks-key`, same-origin guard and one-shot
+     * `onUnauthorized` retry as `request`; never throws on a non-2xx status. `Accept`
+     * is left to the caller's headers.
+     */
+    send(path: string, options?: BlocksRequestOptions): Promise<Response>;
     external<T = unknown>(url: string, options?: BlocksExternalRequestOptions): Promise<T>;
 }
+export declare function parseBody(response: Response): Promise<unknown>;

package/dist/http/http-client.js

@@ -11,11 +11,26 @@ export class BlocksHttpClient {
             throw new Error("Blocks client requires fetch.");
     }
     async request(path, options = {}) {
+        const response = await this.send(path, { ...options, headers: withJsonAccept(options.headers) });
+        const body = await parseBody(response);
+        if (!response.ok)
+            throw new BlocksApiError(response.status, response.statusText, body);
+        return body;
+    }
+    /**
+     * What: sends a Blocks API request and returns the raw `Response`, unread.
+     * Why: some answers carry meaning in the status and headers rather than only the
+     * body -- a function invocation's 202 vs. its synchronous answer, `Retry-After`,
+     * a streamed body -- which `request` reduces to parsed JSON.
+     * How: same credentials, `x-blocks-key`, same-origin guard and one-shot
+     * `onUnauthorized` retry as `request`; never throws on a non-2xx status. `Accept`
+     * is left to the caller's headers.
+     */
+    async send(path, options = {}) {
         const url = buildUrl(this.config.apiUrl, path, options.query);
         const rawBody = isBodyInit(options.body) ? options.body : undefined;
-        const send = async (accessTokenOverride) => {
+        const attempt = async (accessTokenOverride) => {
             const headers = new Headers(options.headers);
-            headers.set("Accept", "application/json");
             headers.set("x-blocks-key", this.config.xBlocksKey);
             if (options.body !== undefined && !rawBody && !headers.has("Content-Type")) {
                 headers.set("Content-Type", "application/json");
@@ -31,10 +46,11 @@ export class BlocksHttpClient {
                 // without this the browser never sends it back on subsequent Blocks API calls.
                 credentials: "include",
                 headers,
-                method: options.method ?? (options.body === undefined ? "GET" : "POST")
+                method: options.method ?? (options.body === undefined ? "GET" : "POST"),
+                signal: options.signal
             });
         };
-        let response = await send();
+        let response = await attempt();
         // A 401 on a token the caller supplied directly (options.accessToken) is the
         // caller's problem to resolve, not ours. Otherwise, give the app one chance to
         // recover through its own onUnauthorized hook (expected to dedupe concurrent
@@ -42,12 +58,9 @@ export class BlocksHttpClient {
         if (response.status === 401 && options.auth !== false && options.accessToken === undefined && this.config.onUnauthorized) {
             const freshToken = await this.config.onUnauthorized();
             if (freshToken)
-                response = await send(freshToken);
+                response = await attempt(freshToken);
         }
-        const body = await parseBody(response);
-        if (!response.ok)
-            throw new BlocksApiError(response.status, response.statusText, body);
-        return body;
+        return response;
     }
     async external(url, options = {}) {
         const response = await this.fetchImpl(url, {
@@ -78,6 +91,12 @@ function sameOriginOnly(path, baseUrl) {
     }
     return target;
 }
+/** `request` always asks for JSON, as it did before `send` existed. */
+function withJsonAccept(headers) {
+    const merged = new Headers(headers);
+    merged.set("Accept", "application/json");
+    return merged;
+}
 function isBodyInit(value) {
     return typeof Blob !== "undefined" && value instanceof Blob
         || typeof FormData !== "undefined" && value instanceof FormData
@@ -91,12 +110,19 @@ function buildUrl(baseUrl, path, query) {
         ? sameOriginOnly(path, baseUrl)
         : new URL(path.replace(/^\/+/, ""), `${baseUrl}/`);
     for (const [key, value] of Object.entries(query ?? {})) {
-        if (value !== undefined)
+        if (value === undefined)
+            continue;
+        if (Array.isArray(value)) {
+            for (const item of value)
+                url.searchParams.append(key, String(item));
+        }
+        else {
             url.searchParams.set(key, String(value));
+        }
     }
     return url.toString();
 }
-async function parseBody(response) {
+export async function parseBody(response) {
     if (response.status === 204)
         return undefined;
     const text = await response.text();

package/dist/iam/iam-client.d.ts

@@ -1,5 +1,5 @@
 import { BlocksHttpClient } from "../http/http-client.js";
-import { BlocksBaseResponse, BlocksGetMyOrganizationsResponse, BlocksGetOrganizationResponse, BlocksGetOrganizationsResponse, BlocksGetPermissionResponse, BlocksGetPermissionsResponse, BlocksGetRoleResponse, BlocksGetRolesResponse, BlocksGetUserResponse, BlocksGetUsersResponse, BlocksIamListRequest, BlocksMeResponse } from "./types.js";
+import { BlocksActivateUserRequest, BlocksBaseResponse, BlocksGetMyOrganizationsResponse, BlocksGetOrganizationResponse, BlocksGetOrganizationsResponse, BlocksGetPermissionResponse, BlocksGetPermissionsResponse, BlocksGetRoleResponse, BlocksGetRolesResponse, BlocksGetUserResponse, BlocksGetUsersResponse, BlocksIamListRequest, BlocksMeResponse } from "./types.js";
 export declare class BlocksIAMClient {
     private readonly http;
     constructor(http: BlocksHttpClient);
@@ -36,9 +36,10 @@ export declare class BlocksIAMClient {
         /**
          * What: activates a user through `POST /iam/v4/iam/users/activate`.
          * Why: admin UIs need to restore access for a previously inactive account.
-         * How: pass IAM's activate payload for the target user.
+         * How: pass `userId` and a non-empty `reason` -- IAM requires the reason (deactivate does
+         * not take one) and answers 400 without it.
          */
-        activate: (request: Record<string, unknown>) => Promise<BlocksBaseResponse>;
+        activate: (request: BlocksActivateUserRequest) => Promise<BlocksBaseResponse>;
         /**
          * What: queries users through `POST /iam/v4/iam/users`.
          * Why: IAM uses a POST-read contract for paging/filtering user lists.
@@ -66,18 +67,23 @@ export declare class BlocksIAMClient {
          */
         revokeAccess: (request: Record<string, unknown>) => Promise<BlocksBaseResponse>;
         /**
-         * What: checks email availability through `GET /iam/v4/iam/email/available`.
+         * What: checks email availability through `POST /iam/v4/iam/email/available`.
          * Why: signup and invite forms can validate duplicate email state before submit.
-         * How: pass the email query fields IAM expects; this is public but still sends `x-blocks-key`.
-         */
-        emailAvailable: (query: Record<string, string | undefined>) => Promise<{
+         * How: pass `{ email }` as a signed-in user whose role has `blocks-iam::iam::email-available` -- IAM
+         * protects it since 2026-10-14 (it was public, and it reveals whether an address is registered), so a
+         * pre-login signup form cannot call it. The address travels in the body; IAM deprecated the GET form.
+         */
+        emailAvailable: (query: {
+            email?: string;
+            Email?: string;
+        } & Record<string, string | undefined>) => Promise<{
             isAvailable?: boolean;
             IsAvailable?: boolean;
         }>;
         /**
-         * What: checks whether a user exists through `GET /iam/v4/iam/users/exists`.
+         * What: checks whether a user exists through `POST /iam/v4/iam/users/exists`.
          * Why: account and invite flows may need an existence check by email.
-         * How: pass the email string; the SDK sends it as the `email` query parameter.
+         * How: pass the email string; it is sent in the body (IAM deprecated the GET form).
          */
         exists: (email: string) => Promise<unknown>;
     };
@@ -181,9 +187,11 @@ export declare class BlocksIAMClient {
         /**
          * What: lists organizations through `GET /iam/v4/iam/organizations`.
          * Why: admin UIs need organization browsing and selection.
-         * How: pass IAM-supported query fields such as paging/search options.
+         * How: pass IAM's query fields -- `Page` (from 0), `PageSize`, `Filter.Search`, `Filter.IsDisabled`,
+         * `Filter.ParentOrganizationId`, `Filter.Ids` (an array). IAM refuses any `Filter.*` field unless
+         * `Filter.Search` is a non-empty term; to filter without a search, filter the returned list instead.
          */
-        list: (query?: Record<string, string | number | boolean | undefined>) => Promise<BlocksGetOrganizationsResponse>;
+        list: (query?: Record<string, string | number | boolean | ReadonlyArray<string> | undefined>) => Promise<BlocksGetOrganizationsResponse>;
         /**
          * What: reads one organization through `GET /iam/v4/iam/organizations/{id}`.
          * Why: organization detail screens need one organization record.

package/dist/iam/iam-client.js

@@ -40,7 +40,8 @@ export class BlocksIAMClient {
         /**
          * What: activates a user through `POST /iam/v4/iam/users/activate`.
          * Why: admin UIs need to restore access for a previously inactive account.
-         * How: pass IAM's activate payload for the target user.
+         * How: pass `userId` and a non-empty `reason` -- IAM requires the reason (deactivate does
+         * not take one) and answers 400 without it.
          */
         activate: (request) => this.http.request("/iam/v4/iam/users/activate", { body: request }),
         /**
@@ -70,20 +71,21 @@ export class BlocksIAMClient {
          */
         revokeAccess: (request) => this.http.request("/iam/v4/iam/users/revoke-access", { body: request }),
         /**
-         * What: checks email availability through `GET /iam/v4/iam/email/available`.
+         * What: checks email availability through `POST /iam/v4/iam/email/available`.
          * Why: signup and invite forms can validate duplicate email state before submit.
-         * How: pass the email query fields IAM expects; this is public but still sends `x-blocks-key`.
+         * How: pass `{ email }` as a signed-in user whose role has `blocks-iam::iam::email-available` -- IAM
+         * protects it since 2026-10-14 (it was public, and it reveals whether an address is registered), so a
+         * pre-login signup form cannot call it. The address travels in the body; IAM deprecated the GET form.
          */
         emailAvailable: (query) => this.http.request("/iam/v4/iam/email/available", {
-            auth: false,
-            query
+            body: { email: query.email ?? query.Email }
         }),
         /**
-         * What: checks whether a user exists through `GET /iam/v4/iam/users/exists`.
+         * What: checks whether a user exists through `POST /iam/v4/iam/users/exists`.
          * Why: account and invite flows may need an existence check by email.
-         * How: pass the email string; the SDK sends it as the `email` query parameter.
+         * How: pass the email string; it is sent in the body (IAM deprecated the GET form).
          */
-        exists: (email) => this.http.request("/iam/v4/iam/users/exists", { query: { email } })
+        exists: (email) => this.http.request("/iam/v4/iam/users/exists", { body: { email } })
     };
     permissions = {
         /**
@@ -185,7 +187,9 @@ export class BlocksIAMClient {
         /**
          * What: lists organizations through `GET /iam/v4/iam/organizations`.
          * Why: admin UIs need organization browsing and selection.
-         * How: pass IAM-supported query fields such as paging/search options.
+         * How: pass IAM's query fields -- `Page` (from 0), `PageSize`, `Filter.Search`, `Filter.IsDisabled`,
+         * `Filter.ParentOrganizationId`, `Filter.Ids` (an array). IAM refuses any `Filter.*` field unless
+         * `Filter.Search` is a non-empty term; to filter without a search, filter the returned list instead.
          */
         list: (query = {}) => this.http.request("/iam/v4/iam/organizations", { query }),
         /**

package/dist/iam/types.d.ts

@@ -1,3 +1,9 @@
+/** `POST /iam/v4/iam/users/activate`. IAM requires both fields. */
+export type BlocksActivateUserRequest = {
+    userId: string;
+    /** Why the account is re-enabled. Required by IAM; an empty value is refused. */
+    reason: string;
+};
 export type BlocksBaseResponse = Record<string, unknown> & {
     errors?: unknown;
     isSuccess?: boolean;

package/dist/index.d.ts

@@ -8,14 +8,18 @@ export { BlocksApiError } from "./http/errors.js";
 export type { BlocksHttpClient } from "./http/http-client.js";
 export { BlocksIAMClient } from "./iam/iam-client.js";
 export { BlocksLocalizationClient } from "./localization/localization-client.js";
+export { BlocksLogicClient } from "./logic/logic-client.js";
+export { BlocksFunctionRunError, BlocksFunctionsClient } from "./logic/functions-client.js";
+export { BlocksProxyClient } from "./logic/proxy-client.js";
 export { BlocksMailClient } from "./mail/mail-client.js";
 export { BlocksMfaClient } from "./mfa/mfa-client.js";
 export { BlocksNotifierClient } from "./notifier/notifier-client.js";
 export type { BlocksAuthJsonOptions, BlocksAuthPassThroughResponse, BlocksAuthResponse, BlocksClientCredentialsRequest, BlocksAuthLoginRequest, BlocksIdpCallbackRequest, BlocksIdpInitiateRequest, BlocksIdpInitiateResponse, BlocksLoginOption, BlocksLogoutRequest, BlocksOidcRefreshRequest, BlocksOidcUserInfo, BlocksRefreshRequest, BlocksSocialLoginRequest, BlocksSwitchOrganizationRequest } from "./auth/auth-client.js";
 export type { BlocksExternalRequestOptions, BlocksRequestOptions } from "./types.js";
-export type { BlocksBaseResponse, BlocksGetMyOrganizationsResponse, BlocksGetOrganizationResponse, BlocksGetOrganizationsResponse, BlocksGetPermissionResponse, BlocksGetPermissionsResponse, BlocksGetRoleResponse, BlocksGetRolesResponse, BlocksGetUserResponse, BlocksGetUsersResponse, BlocksIamListRequest, BlocksMeResponse, BlocksOrganization, BlocksPermission, BlocksQueryListResponse, BlocksQueryResponse, BlocksRole, BlocksUser } from "./iam/types.js";
+export type { BlocksActivateUserRequest, BlocksBaseResponse, BlocksGetMyOrganizationsResponse, BlocksGetOrganizationResponse, BlocksGetOrganizationsResponse, BlocksGetPermissionResponse, BlocksGetPermissionsResponse, BlocksGetRoleResponse, BlocksGetRolesResponse, BlocksGetUserResponse, BlocksGetUsersResponse, BlocksIamListRequest, BlocksMeResponse, BlocksOrganization, BlocksPermission, BlocksQueryListResponse, BlocksQueryResponse, BlocksRole, BlocksUser } from "./iam/types.js";
 export type { BlocksDataCollection, BlocksDataCollectionOptions, BlocksDataDeleteOptions, BlocksDataGetOptions, BlocksDataListOptions, BlocksDataSchema, BlocksDirectoryCreateRequest, BlocksDirectoryDeleteRequest, BlocksDirectoryMoveRequest, BlocksDirectoryUpdateRequest, BlocksFileCopyRequest, BlocksFileCreateVersionRequest, BlocksFileDeleteRequest, BlocksFileGetOptions, BlocksFileInfoListRequest, BlocksFileListRequest, BlocksFileMoveRequest, BlocksFileRenameRequest, BlocksFileUpdateAdditionalInfoRequest, BlocksFileUploadRequest, BlocksFileVersionsRequest, BlocksGraphqlRequest, BlocksLocalStorageUploadRequest, BlocksPagedResult, BlocksRegexGenerateRequest, BlocksSchemaFieldValidationOptions, BlocksSchemaListOptions, BlocksSchemaValidationListOptions, BlocksStorageAccessPolicyRequest, BlocksStorageEffect, BlocksStorageObject, BlocksStorageObjectListRequest, BlocksStorageObjectPageRequest, BlocksStorageObjectSearchRequest, BlocksStorageObjectsResponse, BlocksStorageObjectType, BlocksStoragePermission, BlocksStoragePermissionFlags, BlocksStoragePrincipalType, BlocksStorageResourceRequest, BlocksStorageResourceType, BlocksStorageRevokeAccessRequest, BlocksStorageShareRequest, BlocksStorageToggleInheritanceRequest, BlocksUploadToUrlRequest } from "./data/types.js";
 export type { BlocksLocalizationDictionary, BlocksLocalizationKey, BlocksLocalizationKeyResource, BlocksLocalizationKeysByNamesRequest, BlocksLocalizationKeysByNamesResponse, BlocksLocalizationLanguage, BlocksLocalizationModule, BlocksLocalizationTranslationOptions } from "./localization/types.js";
 export type { BlocksMfaBackupCodeUseRequest, BlocksMfaConfig, BlocksMfaConfigSaveRequest, BlocksMfaGenerateRequest, BlocksMfaPassThroughResponse, BlocksMfaResendRequest, BlocksMfaSetMethodRequest, BlocksMfaVerifyRequest, BlocksMfaVerifyTotpSetupRequest } from "./mfa/types.js";
 export type { BlocksMailPassThroughResponse, BlocksSendMailRequest, BlocksSendMailToAnyRequest } from "./mail/types.js";
 export type { BlocksGetNotificationsOptions, BlocksGetNotificationsResponse, BlocksGetUnreadNotificationsBySubscriptionFilterRequest, BlocksMarkNotificationAsReadRequest, BlocksNotifierPassThroughResponse, BlocksNotifierSubscriptionFilter, BlocksNotifyRequest, BlocksOfflineNotification } from "./notifier/types.js";
+export type { BlocksFunctionAccepted, BlocksFunctionAnswer, BlocksFunctionCallOptions, BlocksFunctionInvokeOptions, BlocksFunctionInvokeResult, BlocksFunctionRunResult, BlocksFunctionTerminalStatus, BlocksFunctionWaitOptions, BlocksHttpMethod, BlocksProxyRequestOptions, BlocksQueryValue } from "./logic/types.js";

package/dist/index.js

@@ -4,6 +4,9 @@ export { BlocksDataClient } from "./data/data-client.js";
 export { BlocksApiError } from "./http/errors.js";
 export { BlocksIAMClient } from "./iam/iam-client.js";
 export { BlocksLocalizationClient } from "./localization/localization-client.js";
+export { BlocksLogicClient } from "./logic/logic-client.js";
+export { BlocksFunctionRunError, BlocksFunctionsClient } from "./logic/functions-client.js";
+export { BlocksProxyClient } from "./logic/proxy-client.js";
 export { BlocksMailClient } from "./mail/mail-client.js";
 export { BlocksMfaClient } from "./mfa/mfa-client.js";
 export { BlocksNotifierClient } from "./notifier/notifier-client.js";

package/dist/logic/functions-client.d.ts

@@ -0,0 +1,73 @@
+import { BlocksHttpClient } from "../http/http-client.js";
+import { BlocksFunctionAccepted, BlocksFunctionCallOptions, BlocksFunctionInvokeOptions, BlocksFunctionInvokeResult, BlocksFunctionRunResult, BlocksFunctionWaitOptions } from "./types.js";
+/** A run that finished without an answer: FAILED, TIMED_OUT, CANCELLED or RESOURCE_EXCEEDED. */
+export declare class BlocksFunctionRunError extends Error {
+    readonly runId: string;
+    readonly status: string;
+    readonly errorCode?: string | null | undefined;
+    readonly errorMessage?: string | null | undefined;
+    constructor(runId: string, status: string, errorCode?: string | null | undefined, errorMessage?: string | null | undefined);
+}
+/**
+ * Calling deployed Blocks functions from app code. Creating, saving, deploying and
+ * inspecting functions is CLI work (`blocks logic function *`), not exposed here.
+ */
+export declare class BlocksFunctionsClient {
+    private readonly http;
+    private readonly apiUrl;
+    constructor(http: BlocksHttpClient, apiUrl: string);
+    /**
+     * What: the absolute public URL of a function (optionally with a sub-path).
+     * Why: third parties (webhooks, other backends) call the function directly and need its address.
+     * How: callers send this project's `x-blocks-key`, plus a Blocks bearer token unless the trigger is Public.
+     */
+    url(functionId: string, path?: string): string;
+    /**
+     * What: invokes a deployed function and returns either its answer or the queued run.
+     * Why: functions run async (202 + poll token) unless deployed as sync, and callers need to know which happened.
+     * How: `kind: "answered"` carries the function's own status/headers/body; `kind: "accepted"` carries
+     * `runId` + `pollToken` for `waitForResult`. Any non-2xx is thrown as `BlocksApiError` -- the platform's
+     * refusals (`FUNCTION_INVOKE_*` codes: 401/403/404/405/413/429/503), a failed or timed-out sync run
+     * (502/504 with `runId`), and a status the function chose itself. Use `call` for just the value.
+     */
+    invoke<T = unknown>(functionId: string, options?: BlocksFunctionInvokeOptions): Promise<BlocksFunctionInvokeResult<T>>;
+    /**
+     * What: invokes a function and returns the unread `Response`.
+     * Why: a streaming function (an `async function*` handler) sends its pieces as they come; reading
+     * them needs the body stream, which `invoke` buffers.
+     * How: same request as `invoke`. Pass `headers: { Accept: "text/event-stream" }` for Server-Sent
+     * Events (`data:` per piece, then `event: done` or `event: error`); otherwise the pieces arrive as
+     * chunked text. Never throws on a non-2xx status -- check `response.ok`.
+     */
+    invokeRaw(functionId: string, options?: BlocksFunctionInvokeOptions): Promise<Response>;
+    /**
+     * What: reads a queued run's status and, once it finished, its result.
+     * Why: an async invocation answers 202 at once; this is how its outcome is collected.
+     * How: pass the `runId` and `pollToken` from the 202. No user session is needed -- the token is
+     * the capability -- and any wrong, expired or foreign token is the same 404.
+     */
+    getResult(runId: string, pollToken: string, options?: {
+        signal?: AbortSignal;
+    }): Promise<BlocksFunctionRunResult>;
+    /**
+     * What: the full run record (input, result, attempts, timings) for a signed-in caller.
+     * Why: an admin screen or a caller without a poll token may need the whole run.
+     * How: requires the `blocks-logic::function::read` permission; reads within the caller's own tenant.
+     */
+    getRun<T = Record<string, unknown>>(runId: string): Promise<T>;
+    /**
+     * What: polls a queued run until it finishes.
+     * Why: turns the 202 + poll token into the final outcome without hand-written polling.
+     * How: resolves with the terminal `BlocksFunctionRunResult` (check `status`); rejects on `timeoutMs`
+     * (the run itself keeps going) or `signal` abort.
+     */
+    waitForResult(accepted: Pick<BlocksFunctionAccepted, "runId" | "pollToken">, options?: BlocksFunctionWaitOptions): Promise<BlocksFunctionRunResult>;
+    /**
+     * What: invokes a function and returns its value, however it was deployed.
+     * Why: most callers want the handler's return value, not the transport details.
+     * How: a sync answer's body is returned as is; an async run is awaited and its result parsed. A
+     * returned `{ statusCode, headers, body }` is unwrapped to `body` (a 4xx/5xx `statusCode` throws
+     * `BlocksApiError`). A run that fails throws `BlocksFunctionRunError`.
+     */
+    call<T = unknown>(functionId: string, options?: BlocksFunctionCallOptions): Promise<T>;
+}