@seliseblocks/client 0.1.6 → 0.3.0

package/README.md

@@ -1,222 +1,270 @@
-# Blocks Client
-
-Framework-neutral TypeScript SDK for SELISE Blocks frontend and app-runtime code.
-
-`@seliseblocks/client` gives consumer apps a small, typed wrapper around the Blocks APIs they normally call at runtime: Auth/IAM, Data, Localization, and shared HTTP configuration. Detailed `what / why / how` descriptions are kept on the SDK functions themselves so editors and generated typings show the guidance where developers use the API.
-
-Admin/control-plane work belongs in `@seliseblocks/cli-os`: project setup, schema/rules deploy, release deploy, and AI/admin terminal workflows.
-
-For AI agents and automation, see [AI_USAGE_GUIDE.md](AI_USAGE_GUIDE.md).
-
-## Install
-
-```bash
-npm install @seliseblocks/client@latest
-```
-
-Requires Node.js 20+ or a browser/runtime with `fetch`.
-
-## Create A Client
-
-```ts
-import { createBlocksClient } from "@seliseblocks/client";
-
-const blocks = createBlocksClient({
-  apiUrl: "https://api.seliseblocks.com",
-  xBlocksKey: "<blocks-key>",
-  accessToken: () => currentUserSession?.accessToken,
-  oidc: {
-    url: "https://iam.seliseblocks.com",
-    clientId: "<public-browser-client-id>",
-    redirectUri: configuredRedirectUri ?? `${window.location.origin}/login/callback`
-  }
-});
-```
-
-`xBlocksKey` is always sent as the `x-blocks-key` header. Do not send `ProjectKey` or `projectKey` in request query/body payloads.
-
-The SDK does not store tokens. Your app owns login state, refresh scheduling, storage, and logout cleanup.
-
-Use a configured OIDC redirect URI when your app has one. The current-origin `/login/callback` URL is only a browser fallback.
-
-## Auth
-
-Auth has two login flows.
-
-OIDC/hosted IAM login uses `auth.idp`. The SDK relies on Blocks IAM `IdpController`, sends the configured public `clientId`, and does not manually build `oidc/authorize` URLs. Refresh OIDC sessions with `auth.oidc.refreshToken()`, which calls `/iam/v4/oidc/token` and sends `client_id`.
-
-```ts
-await blocks.auth.idp.redirectToProvider();
-
-const result = await blocks.auth.idp.callback(window.location.href);
-
-const refreshed = await blocks.auth.oidc.refreshToken({
-  refreshToken: result.refresh_token,
-  clientId: "<public-browser-client-id>"
-});
-```
-
-Embedded/app-owned login UI uses AuthController methods directly on `auth`: `auth.login()`, `auth.socialInitiate(clientId, redirectUri)` (two positional strings, not an object), `auth.socialCallback(request)`, and `auth.refresh()`.
-
-```ts
-const login = await blocks.auth.login({
-  username: "user@example.com",
-  password: "password"
-});
-
-const refreshed = await blocks.auth.refresh({
-  refreshToken: login.refresh_token
-});
-```
-
-Other auth APIs, such as user info, organization switch, logout, signup, recovery, activation, auth config, user codes, client credentials, and identity providers, can be used by either flow when the app has the required token/permission.
-
-`auth.oidc.clientCredentials()` is for trusted non-browser runtimes only because it requires a client secret.
-
-`auth.accessToken()` resolves the caller-owned bearer token configured on `createBlocksClient` (string or callback). `auth.isAuthenticated()` checks the current session against IAM through `GET /iam/v4/auth/me` and returns a boolean based on the raw response status - use it instead of `userInfo()` when you need a true/false signal, since IAM's hosted IdP flow may set the session as a cookie with no local `accessToken` to inspect.
-
-```ts
-const config = await blocks.mfa.config();
-await blocks.mfa.totp.setup();
-await blocks.mfa.totp.verifySetup({ code: "123456" });
-await blocks.mfa.setMethod({ mfaType: 1 });
-const backupCodes = await blocks.mfa.backupCodes.generate();
-```
-
-## Mail And Notifications
-
-```ts
-await blocks.mail.send({
-  to: ["user@example.com"],
-  purpose: "welcome",
-  language: "en",
-  subjectDataContext: { firstName: "Ada" }
-});
-
-await blocks.mail.sendToAny({
-  to: ["qa@example.com"],
-  purpose: "welcome",
-  language: "en",
-  isTestMail: true
-});
-
-await blocks.notifier.notify({
-  userIds: ["user-id"],
-  denormalizedPayload: JSON.stringify({ orderId: "123" }),
-  saveDenormalizedPayloadAsAnObject: true
-});
-
-const inbox = await blocks.notifier.getNotifications({ isUnreadOnly: true, page: 1, pageSize: 20 });
-await blocks.notifier.markNotificationAsRead({ id: inbox.notifications[0].id });
-await blocks.notifier.markAllNotificationAsRead();
-```
-
-`mail.send`/`mail.sendToAny` call `/logic/v4/Mail/Send`/`SendToAny`. `notifier.*` calls `/logic/v4/Notifier/*`
-for sending/reading notifications; tenant notification *channel configuration* (`/os/v4/Notification/*`)
-is an admin concern handled by `@seliseblocks/cli-os`'s `notification *` commands, not this SDK.
-
-## Common Runtime Calls
-
-```ts
-const me = await blocks.iam.me();
-const orgs = await blocks.iam.organizations.my();
-const features = await blocks.iam.resources.features();
-```
-
-`iam.organizations.my()` returns the IAM envelope with `organizations`, not `data`.
-
-```ts
-const schemas = await blocks.data.schemas.list();
-const schemaInfo = await blocks.data.schemas.infoByName("Student");
-const schemaRules = await blocks.data.validations.bySchemaId("schema-id");
-
-const students = blocks.data.collection("Students");
-const rows = await students.list({ pageNo: 1, pageSize: 20 });
-await students.create({ firstName: "Test" });
-
-const graph = await blocks.data.graphql({
-  query: "{ students { items { itemId firstName } } }"
-});
-```
-
-```ts
-const upload = await blocks.data.files.presignedUploadUrl({
-  name: "avatar.png",
-  configurationName: "default",
-  parentDirectoryId: "root",
-  accessModifier: "Private"
-});
-
-await blocks.data.files.uploadToUrl({
-  url: upload.uploadUrl,
-  body: file,
-  contentType: file.type
-});
-
-const items = await blocks.data.objects.list({
-  parentDirectoryId: "root",
-  limit: 20
-});
-
-const directory = await blocks.data.directories.create({
-  name: "Contracts",
-  parentDirectoryId: "root",
-  allowedFileExtensions: ["pdf", "docx"]
-});
-```
-
-```ts
-await blocks.localization.load("en-US", ["common", "dashboard"]);
-const label = blocks.localization.t("dashboard.title", "Dashboard");
-
-const tenantLanguages = await blocks.localization.languagesForCurrentTenant();
-const selectedKeys = await blocks.localization.keysByNames({
-  keyNames: ["dashboard.title"]
-});
-```
-
-## API Surface
-
-- `blocks.auth`: AuthController login, social login, refresh, org switch, logout, signup, recovery, activation, auth config, user codes, client credentials, identity providers.
-- `blocks.auth.idp`: hosted IdP initiate, browser redirect, callback, UI config.
-- `blocks.auth.oidc`: refresh-token and client-credentials token endpoint helpers.
-- `blocks.iam`: current user, users, roles, permissions, resources, organizations, signup settings (`blocks.iam.signupSettings`).
-- `blocks.data`: schema reads, validation reads, GraphQL gateway execution, file/directory/object-tree storage helpers, and runtime collection CRUD.
-- `blocks.localization`: tenant language/module discovery, UILM dictionary loading, selected key lookup, simple `t()` lookup.
-- `blocks.mfa`: tenant MFA policy read/save, TOTP enrollment, OTP generate/resend/verify, method switch, disable, and backup codes.
-- `blocks.mail`: `send`/`sendToAny` transactional email through the tenant's configured mail provider.
-- `blocks.notifier`: `notify`, `getNotifications`, `getUnreadNotificationsBySubscriptionFilter`, `markNotificationAsRead`, `markAllNotificationAsRead`.
-
-Professional class names are exported for advanced typing and adapters: `BlocksAuthenticationClient`, `BlocksIAMClient`, `BlocksDataClient`, `BlocksLocalizationClient`, `BlocksMfaClient`, `BlocksMailClient`, and `BlocksNotifierClient`. `BlocksApiError` is exported for typed error handling - every non-2xx response from `http.request`/`http.external` throws it, exposing `status`, `statusText`, and the parsed `body`:
-
-```ts
-try {
-  await blocks.iam.me();
-} catch (error) {
-  if (error instanceof BlocksApiError) {
-    console.error(error.status, error.body);
-  }
-}
-```
-
-## Boundaries
-
-This package must not contain:
-
-- CLI client secrets
-- impersonation APIs
-- project create/list/use
-- schema/rules deploy
-- release deploy
-- token/session/PKCE storage
-- Node filesystem or OS credential storage
-- framework UI components
-- Localization authoring/admin endpoints
-- Data schema/rules mutation endpoints
-
-## Package Checks
-
-```bash
-npm test
-npm pack --dry-run
-```
+# Blocks Client
+
+Framework-neutral TypeScript SDK for SELISE Blocks frontend and app-runtime code.
+
+[`@seliseblocks/client`](https://www.npmjs.com/package/@seliseblocks/client) gives consumer apps a small, typed wrapper around the Blocks APIs they normally call at runtime: Auth/IAM, Data, Localization, and shared HTTP configuration. Detailed `what / why / how` descriptions are kept on the SDK functions themselves so editors and generated typings show the guidance where developers use the API.
+
+Admin/control-plane work belongs in `@seliseblocks/cli-os`: project setup, schema/rules deploy, release deploy, and AI/admin terminal workflows.
+
+For AI agents and automation, see [AGENT_GUIDE.md](AGENT_GUIDE.md).
+
+## Install
+
+```bash
+npm install @seliseblocks/client@latest
+```
+
+Requires Node.js 20+ or a browser/runtime with `fetch`.
+
+## Create A Client
+
+```ts
+import { createBlocksClient } from "@seliseblocks/client";
+
+const blocks = createBlocksClient({
+  apiUrl: "https://api.seliseblocks.com",
+  xBlocksKey: "<blocks-key>",
+  accessToken: () => currentUserSession?.accessToken,
+  oidc: {
+    url: "https://iam.seliseblocks.com",
+    clientId: "<public-browser-client-id>",
+    redirectUri: configuredRedirectUri ?? `${window.location.origin}/login/callback`
+  }
+});
+```
+
+`xBlocksKey` is always sent as the `x-blocks-key` header. Do not send `ProjectKey` or `projectKey` in request query/body payloads.
+
+The SDK does not store tokens. Your app owns login state, refresh scheduling, storage, and logout cleanup.
+
+`blocks.config` reads back the resolved settings (`apiUrl`, `xBlocksKey`,
+`appDomain`, `oidc`). It deliberately excludes your `accessToken` resolver and
+`onUnauthorized` hook, so the client never doubles as a place to read a live
+session out of; use `await blocks.auth.accessToken()` when you need the token.
+
+`http.request()` only ever talks to the configured `apiUrl` — it attaches your
+bearer token, `x-blocks-key`, and cookies, so an absolute URL on another origin
+is refused rather than handed a live session. Use `http.external(url)` for
+third-party URLs such as a pre-signed storage upload; it sends no Blocks
+credentials.
+
+Use a configured OIDC redirect URI when your app has one. The current-origin `/login/callback` URL is only a browser fallback.
+
+## Auth
+
+Auth has two login flows.
+
+OIDC/hosted IAM login uses `auth.idp`. The SDK relies on Blocks IAM `IdpController`, sends the configured public `clientId`, and does not manually build `oidc/authorize` URLs. Refresh OIDC sessions with `auth.oidc.refreshToken()`, which calls `/iam/v4/oidc/token` and sends `client_id`.
+
+```ts
+await blocks.auth.idp.redirectToProvider();
+
+const result = await blocks.auth.idp.callback(window.location.href);
+
+const refreshed = await blocks.auth.oidc.refreshToken({
+  refreshToken: result.refresh_token,
+  clientId: "<public-browser-client-id>"
+});
+```
+
+Embedded/app-owned login UI uses AuthController methods directly on `auth`: `auth.login()`, `auth.socialInitiate(clientId, redirectUri)` (two positional strings, not an object), `auth.socialCallback(request)`, and `auth.refresh()`.
+
+```ts
+const login = await blocks.auth.login({
+  username: "user@example.com",
+  password: "password"
+});
+
+const refreshed = await blocks.auth.refresh({
+  refreshToken: login.refresh_token
+});
+```
+
+Other auth APIs, such as user info, organization switch, logout, signup, recovery, activation, auth config, user codes, client credentials, and identity providers, can be used by either flow when the app has the required token/permission.
+
+`auth.oidc.clientCredentials()` is for trusted non-browser runtimes only because it requires a client secret.
+
+`auth.accessToken()` resolves the caller-owned bearer token configured on `createBlocksClient` (string or callback). `auth.isAuthenticated()` checks the current session against IAM through `GET /iam/v4/auth/me` and returns a boolean based on the raw response status - use it instead of `userInfo()` when you need a true/false signal, since IAM's hosted IdP flow may set the session as a cookie with no local `accessToken` to inspect.
+
+## MFA
+
+`blocks.mfa` covers the signed-in user's own multi-factor setup — TOTP
+enrollment, OTP challenges, switching the active method, and backup codes —
+plus `mfa.saveConfig()` for tenant-wide MFA policy, which needs an admin
+token.
+
+```ts
+const config = await blocks.mfa.config();
+await blocks.mfa.totp.setup();
+await blocks.mfa.totp.verifySetup({ code: "123456" });
+await blocks.mfa.setMethod({ mfaType: 1 });
+const backupCodes = await blocks.mfa.backupCodes.generate();
+```
+
+## Mail And Notifications
+
+```ts
+await blocks.mail.send({
+  to: ["user@example.com"],
+  purpose: "welcome",
+  language: "en",
+  subjectDataContext: { firstName: "Ada" }
+});
+
+await blocks.mail.sendToAny({
+  to: ["qa@example.com"],
+  purpose: "welcome",
+  language: "en",
+  isTestMail: true
+});
+
+await blocks.notifier.notify({
+  configurationName: "in-app", // the `name` of a notification configuration in this project
+  userIds: ["user-id"],
+  denormalizedPayload: JSON.stringify({ orderId: "123" }),
+  saveDenormalizedPayloadAsAnObject: true
+});
+
+const inbox = await blocks.notifier.getNotifications({ isUnreadOnly: true, page: 1, pageSize: 20 });
+await blocks.notifier.markNotificationAsRead({ id: inbox.notifications[0].id });
+await blocks.notifier.markAllNotificationAsRead();
+```
+
+`mail.send`/`mail.sendToAny` call `/logic/v4/Mail/Send`/`SendToAny`. `notifier.*` calls `/logic/v4/Notifier/*`
+for sending/reading notifications; tenant notification *channel configuration* (`/os/v4/Notification/*`)
+is an admin concern handled by `@seliseblocks/cli-os`'s `notification *` commands, not this SDK.
+
+## Functions And Proxies
+
+```ts
+// A deployed Blocks function -- sync or async, you get the value:
+const quote = await blocks.logic.functions.call<{ total: number }>("<functionId>", {
+  path: "quotes",
+  body: { items: [{ sku: "A1", qty: 2 }] }
+});
+
+// Or the transport-level result:
+const outcome = await blocks.logic.functions.invoke("<functionId>", { respondAsync: true });
+if (outcome.kind === "accepted") {
+  const run = await blocks.logic.functions.waitForResult(outcome, { timeoutMs: 30_000 });
+}
+
+// A third-party API through a Blocks proxy (upstream URL and keys stay server-side):
+const charge = await blocks.logic.proxy.request("stripe", { path: "charges/ch_123" });
+```
+
+A failed or timed-out run throws `BlocksFunctionRunError`; platform refusals throw `BlocksApiError`
+(`body.code` is `FUNCTION_INVOKE_*` or `PROXY_GATEWAY_*`). `invokeRaw()` returns the unread `Response`
+for streaming handlers. Creating, saving and deploying functions and configuring proxies is CLI work
+(`blocks logic function|proxy *`).
+
+Writing a function? Its handler types ship type-only under a subpath:
+
+```js
+/** @type {import("@seliseblocks/client/functions").FunctionHandler} */
+export default async function handler(input, ctx) {
+  ctx.log.info("called", { path: input.path });
+  return { ok: true, region: ctx.env.REGION };
+}
+```
+
+## Common Runtime Calls
+
+```ts
+const me = await blocks.iam.me();
+const orgs = await blocks.iam.organizations.my();
+const features = await blocks.iam.resources.features();
+```
+
+`iam.organizations.my()` returns the IAM envelope with `organizations`, not `data`.
+
+```ts
+const schemas = await blocks.data.schemas.list();
+const schemaInfo = await blocks.data.schemas.infoByName("Student");
+const schemaRules = await blocks.data.validations.bySchemaId("schema-id");
+
+const students = blocks.data.collection("Students");
+const rows = await students.list({ pageNo: 1, pageSize: 20 });
+await students.create({ firstName: "Test" });
+
+const graph = await blocks.data.graphql({
+  query: "{ students { items { itemId firstName } } }"
+});
+```
+
+```ts
+const upload = await blocks.data.files.presignedUploadUrl({
+  name: "avatar.png",
+  configurationName: "default",
+  parentDirectoryId: "root",
+  accessModifier: "Private"
+});
+
+await blocks.data.files.uploadToUrl({
+  url: upload.uploadUrl,
+  body: file,
+  contentType: file.type
+});
+
+const items = await blocks.data.objects.list({
+  parentDirectoryId: "root",
+  limit: 20
+});
+
+const directory = await blocks.data.directories.create({
+  name: "Contracts",
+  parentDirectoryId: "root",
+  allowedFileExtensions: ["pdf", "docx"]
+});
+```
+
+```ts
+await blocks.localization.load("en-US", ["common", "dashboard"]);
+const label = blocks.localization.t("dashboard.title", "Dashboard");
+
+const tenantLanguages = await blocks.localization.languagesForCurrentTenant();
+const selectedKeys = await blocks.localization.keysByNames({
+  keyNames: ["dashboard.title"]
+});
+```
+
+## API Surface
+
+See [`AGENT_GUIDE.md`](AGENT_GUIDE.md)'s Service Map for the full method-level
+list under `blocks.auth`, `blocks.iam`, `blocks.data`, `blocks.localization`,
+`blocks.logic`, `blocks.mfa`, `blocks.mail`, and `blocks.notifier`.
+
+Professional class names are exported for advanced typing and adapters: `BlocksAuthenticationClient`, `BlocksIAMClient`, `BlocksDataClient`, `BlocksLocalizationClient`, `BlocksLogicClient` (with `BlocksFunctionsClient` / `BlocksProxyClient` and `BlocksFunctionRunError`), `BlocksMfaClient`, `BlocksMailClient`, and `BlocksNotifierClient`. `BlocksApiError` is exported for typed error handling - every non-2xx response from `http.request`/`http.external` throws it, exposing `status`, `statusText`, and the parsed `body`. That holds even when the body is not really JSON: a proxy or WAF answering with an HTML error page under a JSON content type surfaces as a `BlocksApiError` carrying the status and the raw text, not as a `SyntaxError`.
+
+```ts
+try {
+  await blocks.iam.me();
+} catch (error) {
+  if (error instanceof BlocksApiError) {
+    console.error(error.status, error.body);
+  }
+}
+```
+
+## Boundaries
+
+This package must not contain:
+
+- CLI client secrets
+- impersonation APIs
+- project create/list/use
+- schema/rules deploy
+- release deploy
+- token/session/PKCE storage
+- Node filesystem or OS credential storage
+- framework UI components
+- Localization authoring/admin endpoints
+- Data schema/rules mutation endpoints
+- Function create/save/deploy or proxy configuration endpoints
+
+## Package Checks
+
+```bash
+npm test
+npm pack --dry-run
+```

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

@@ -1,10 +1,10 @@
-import type { RequiredConfig } from "../client.js";
+import type { BlocksResolvedConfig } from "../client.js";
 import type { BlocksAuthJsonOptions, BlocksAuthLoginRequest, BlocksAuthPassThroughResponse, BlocksAuthResponse, BlocksClientCredentialsRequest, BlocksIdpCallbackRequest, BlocksIdpInitiateRequest, BlocksIdpInitiateResponse, BlocksLoginOption, BlocksLogoutRequest, BlocksOidcRefreshRequest, BlocksOidcUserInfo, BlocksRefreshRequest, BlocksSocialLoginRequest, BlocksSwitchOrganizationRequest } from "./types.js";
-export type { BlocksAuthLoginRequest, BlocksAuthPassThroughResponse, BlocksAuthResponse, BlocksClientCredentialsRequest, BlocksIdpCallbackRequest, BlocksIdpInitiateRequest, BlocksIdpInitiateResponse, BlocksLoginOption, BlocksLogoutRequest, BlocksOidcRefreshRequest, BlocksOidcUserInfo, BlocksRefreshRequest, BlocksSocialLoginRequest, BlocksSwitchOrganizationRequest } from "./types.js";
+export type { BlocksAuthJsonOptions, BlocksAuthLoginRequest, BlocksAuthPassThroughResponse, BlocksAuthResponse, BlocksClientCredentialsRequest, BlocksIdpCallbackRequest, BlocksIdpInitiateRequest, BlocksIdpInitiateResponse, BlocksLoginOption, BlocksLogoutRequest, BlocksOidcRefreshRequest, BlocksOidcUserInfo, BlocksRefreshRequest, BlocksSocialLoginRequest, BlocksSwitchOrganizationRequest } from "./types.js";
 export declare class BlocksAuthenticationClient {
     private readonly clientConfig;
     private readonly fetchImpl;
-    constructor(clientConfig: RequiredConfig, fetchImpl?: typeof fetch);
+    constructor(clientConfig: BlocksResolvedConfig, fetchImpl?: typeof fetch);
     /**
      * What: discovers tenant login options through `GET /iam/v4/auth/login-options`.
      * Why: login screens need to know which login methods the tenant supports before rendering controls.
@@ -38,7 +38,8 @@ export declare class BlocksAuthenticationClient {
     /**
      * What: switches the active organization through `POST /iam/v4/auth/switch-org`.
      * Why: multi-organization users need a new IAM response for the selected organization context.
-     * How: pass `organizationId` plus the refresh/session fields IAM expects; then replace app-owned session state with the response if needed.
+     * How: pass `organizationId` (sent as IAM's `organization_id`). IAM reads the refresh token from the session
+     * cookie, so call it from a browser session; then replace app-owned session state with the response if needed.
      */
     switchOrganization(request: BlocksSwitchOrganizationRequest): Promise<BlocksAuthResponse>;
     /**

package/dist/auth/auth-client.js

@@ -62,10 +62,15 @@ export class BlocksAuthenticationClient {
     /**
      * What: switches the active organization through `POST /iam/v4/auth/switch-org`.
      * Why: multi-organization users need a new IAM response for the selected organization context.
-     * How: pass `organizationId` plus the refresh/session fields IAM expects; then replace app-owned session state with the response if needed.
+     * How: pass `organizationId` (sent as IAM's `organization_id`). IAM reads the refresh token from the session
+     * cookie, so call it from a browser session; then replace app-owned session state with the response if needed.
      */
     switchOrganization(request) {
-        return this.json("/iam/v4/auth/switch-org", { body: request });
+        // refreshToken is dropped: IAM never reads it from this body, so sending it only spreads a secret.
+        const { organizationId, refreshToken: _unused, ...rest } = request;
+        return this.json("/iam/v4/auth/switch-org", {
+            body: { ...rest, organization_id: rest.organization_id ?? organizationId }
+        });
     }
     /**
      * What: reads OIDC-style current-user info through `GET /iam/v4/auth/me`.

package/dist/auth/types.d.ts

@@ -55,7 +55,12 @@ export type BlocksLogoutRequest = Record<string, unknown> & {
     refreshToken?: string;
 };
 export type BlocksSwitchOrganizationRequest = Record<string, unknown> & {
+    /** Sent as IAM's `organization_id`. */
     organizationId?: string;
+    /**
+     * @deprecated Not sent. IAM's switch-org reads the refresh token only from the
+     * session cookie (or its `rt_<domain>` header), never from the body.
+     */
     refreshToken?: string;
 };
 export type BlocksOidcRefreshRequest = {

package/dist/client.d.ts

@@ -3,6 +3,7 @@ import { BlocksDataClient } from "./data/data-client.js";
 import { BlocksHttpClient } from "./http/http-client.js";
 import { BlocksIAMClient } from "./iam/iam-client.js";
 import { BlocksLocalizationClient } from "./localization/localization-client.js";
+import { BlocksLogicClient } from "./logic/logic-client.js";
 import { BlocksMailClient } from "./mail/mail-client.js";
 import { BlocksMfaClient } from "./mfa/mfa-client.js";
 import { BlocksNotifierClient } from "./notifier/notifier-client.js";
@@ -58,18 +59,33 @@ export type BlocksClientConfig = {
      */
     xBlocksKey: string;
 };
+/**
+ * The resolved configuration a client exposes on `blocks.config`: the settings
+ * an app may want to read back (which tenant, which API, which OIDC client),
+ * with the caller-owned `accessToken` resolver and `onUnauthorized` hook left
+ * out. Those two are callables that reach live credentials, and this package's
+ * boundary is that it never becomes a place to read a session from -- use
+ * `blocks.auth.accessToken()` when you need the token itself.
+ */
+export type BlocksPublicConfig = Omit<BlocksResolvedConfig, "accessToken" | "onUnauthorized">;
 export type BlocksClient = {
     auth: BlocksAuthenticationClient;
-    config: Readonly<RequiredConfig>;
+    config: Readonly<BlocksPublicConfig>;
     data: BlocksDataClient;
     http: BlocksHttpClient;
     iam: BlocksIAMClient;
     localization: BlocksLocalizationClient;
+    logic: BlocksLogicClient;
     mail: BlocksMailClient;
     mfa: BlocksMfaClient;
     notifier: BlocksNotifierClient;
 };
-export type RequiredConfig = {
+/**
+ * `BlocksClientConfig` after defaults are applied -- the shape the internal
+ * service clients are constructed with. Consumers normally want
+ * `BlocksPublicConfig` (what `blocks.config` actually exposes) instead.
+ */
+export type BlocksResolvedConfig = {
     accessToken?: string | (() => Promise<string | undefined> | string | undefined);
     apiUrl: string;
     appDomain?: string;
@@ -80,9 +96,11 @@ export type RequiredConfig = {
     };
     xBlocksKey: string;
 };
+/** @deprecated Renamed to `BlocksResolvedConfig` for consistency with the other exported names. */
+export type RequiredConfig = BlocksResolvedConfig;
 /**
  * What: creates a framework-neutral Blocks SDK instance for one tenant/app runtime.
- * Why: frontend code needs a single configured entry point for IAM, Auth, Data, and Localization APIs.
+ * Why: frontend code needs a single configured entry point for IAM, Auth, Data, Localization and Logic (functions, proxies) APIs.
  * How: pass `apiUrl` and `xBlocksKey`; optionally pass an `accessToken` callback and OIDC config. The SDK never adds `ProjectKey` and never stores tokens.
  */
 export declare function createBlocksClient(config: BlocksClientConfig): BlocksClient;

package/dist/client.js

@@ -3,25 +3,28 @@ import { BlocksDataClient } from "./data/data-client.js";
 import { BlocksHttpClient } from "./http/http-client.js";
 import { BlocksIAMClient } from "./iam/iam-client.js";
 import { BlocksLocalizationClient } from "./localization/localization-client.js";
+import { BlocksLogicClient } from "./logic/logic-client.js";
 import { BlocksMailClient } from "./mail/mail-client.js";
 import { BlocksMfaClient } from "./mfa/mfa-client.js";
 import { BlocksNotifierClient } from "./notifier/notifier-client.js";
 /**
  * What: creates a framework-neutral Blocks SDK instance for one tenant/app runtime.
- * Why: frontend code needs a single configured entry point for IAM, Auth, Data, and Localization APIs.
+ * Why: frontend code needs a single configured entry point for IAM, Auth, Data, Localization and Logic (functions, proxies) APIs.
  * How: pass `apiUrl` and `xBlocksKey`; optionally pass an `accessToken` callback and OIDC config. The SDK never adds `ProjectKey` and never stores tokens.
  */
 export function createBlocksClient(config) {
     const normalized = normalizeConfig(config);
     const auth = new BlocksAuthenticationClient(normalized, config.fetch);
     const http = new BlocksHttpClient(normalized, auth, config.fetch);
+    const { accessToken: _accessToken, onUnauthorized: _onUnauthorized, ...publicConfig } = normalized;
     return {
         auth,
-        config: normalized,
+        config: publicConfig,
         data: new BlocksDataClient(http),
         http,
         iam: new BlocksIAMClient(http),
         localization: new BlocksLocalizationClient(http),
+        logic: new BlocksLogicClient(http, normalized.apiUrl),
         mail: new BlocksMailClient(http),
         mfa: new BlocksMfaClient(http),
         notifier: new BlocksNotifierClient(http)