@seliseblocks/client 0.1.5 → 0.1.6

package/AI_USAGE_GUIDE.md

@@ -1,165 +1,165 @@
-# AI Usage Guide
-
-Use this file only for `@seliseblocks/client` app-code work. For full method details, read the source docstrings.
-
-Source refs:
-
-- Client setup: `src/client.ts`
-- Auth: `src/auth/auth-client.ts`
-- IAM: `src/iam/iam-client.ts`
-- Data: `src/data/data-client.ts`
-- Localization: `src/localization/localization-client.ts`
-- MFA: `src/mfa/mfa-client.ts`
-- HTTP/errors: `src/http/http-client.ts`, `src/http/errors.ts`
-
-## Non-Negotiable Rules
-
-- Configure `xBlocksKey`; SDK sends it as `x-blocks-key`.
-- Do not send `ProjectKey` or `projectKey`.
-- Do not add `/api` after `/v4`.
-- Valid route shapes: `/iam/v4/...`, `/data/v4/...`, `/localization/v4/...`.
-- SDK does not store tokens. App owns access token, refresh token, storage, and logout cleanup.
-- Frontend code must not contain client secrets.
-- Do not add impersonation, release deploy, schema/rules mutation, or localization authoring/admin APIs.
-
-## Create Client
-
-```ts
-import { createBlocksClient } from "@seliseblocks/client";
-
-export const blocks = createBlocksClient({
-  apiUrl: "https://api.seliseblocks.com",
-  xBlocksKey: env.BLOCKS_KEY,
-  accessToken: () => session.accessToken,
-  oidc: {
-    url: "https://iam.seliseblocks.com",
-    clientId: env.OIDC_CLIENT_ID,
-    redirectUri: env.OIDC_REDIRECT_URI ?? `${window.location.origin}/login/callback`
-  }
-});
-```
-
-Use `accessToken` only for the current token resolver. Do not add SDK token storage.
-Use a configured `redirectUri` when available; the current-origin `/login/callback` URL is only a browser fallback.
-
-## Auth Decision
-
-There are two auth flows.
-
-OIDC/hosted IAM flow:
-
-- Login: `blocks.auth.idp.initiate()`, `blocks.auth.idp.redirectToProvider()`, `blocks.auth.idp.callback(...)`
-- Refresh: `blocks.auth.oidc.refreshToken({ refreshToken })`
-- Refresh route: `POST /iam/v4/oidc/token`
-- Must send `client_id`; SDK uses `request.clientId` or configured `oidc.clientId`.
-- Do not manually build `oidc/authorize`.
-
-Embedded/app-owned flow:
-
-- Login: `blocks.auth.login(...)`
-- Social: `blocks.auth.socialInitiate(clientId, redirectUri)` (two positional strings), `blocks.auth.socialCallback(request)` (object)
-- Refresh: `blocks.auth.refresh({ refreshToken })`
-- Routes: `/iam/v4/auth/login`, `/iam/v4/auth/social/*`, `/iam/v4/auth/refresh`
-
-Shared auth methods for both flows:
-
-- `userInfo()`
-- `switchOrganization(...)`
-- `logout(...)`, `logoutAll(...)`
-- `signup(...)`, `recover(...)`, `resetPassword(...)`
-- `changePassword(...)`
-- `activate(...)`, `resendActivation(...)`, `validateActivation(...)`
-- `identityProviders.*`, `config.*`, `userCodes.*`, `clientCredentials.*` when app has permission
-- `accessToken()` - resolves the caller-owned bearer token configured on `createBlocksClient`.
-- `isAuthenticated()` - checks the session against IAM via `GET /iam/v4/auth/me`, returns a boolean from the raw response status. Prefer this over `userInfo()` for a true/false check, since a hosted-IdP session may live in a cookie with no local `accessToken` to inspect.
-
-## Service Map
-
-IAM:
-
-- `blocks.iam.me()`
-- `blocks.iam.users.*`
-- `blocks.iam.roles.*`
-- `blocks.iam.permissions.*`
-- `blocks.iam.resources.*`
-- `blocks.iam.organizations.*`
-- `blocks.iam.signupSettings.get()` / `.save(...)`
-
-MFA:
-
-- `blocks.mfa.config()` / `.saveConfig(...)` - tenant MFA policy
-- `blocks.mfa.totp.setup()` / `.verifySetup({ code })` - TOTP enrollment
-- `blocks.mfa.generate(...)` / `.resend(...)` / `.verify(...)` - OTP challenge flow
-- `blocks.mfa.setMethod({ mfaType })`, `.disable()`
-- `blocks.mfa.backupCodes.list()` / `.generate()` / `.use({ code, userId })`
-
-Data:
-
-- `blocks.data.schemas.*` for schema reads only
-- `blocks.data.validations.*` for validation reads
-- `blocks.data.collection("Name").list/get/create/update/delete`
-- `blocks.data.graphql(...)`
-- `blocks.data.files.*` for file/storage helpers
-- `blocks.data.directories.*` for directory create/get/update/delete/move
-- `blocks.data.objects.*` for browse/search/trash/shared/restore/share/access/inheritance
-- `blocks.data.utilities.*` for runtime utility helpers
-
-Localization:
-
-- `blocks.localization.languages()`
-- `blocks.localization.modules()`
-- `blocks.localization.languagesForCurrentTenant()`
-- `blocks.localization.modulesForCurrentTenant()`
-- `blocks.localization.translations(moduleName, language)`
-- `blocks.localization.load(language, modules)`
-- `blocks.localization.cloudTranslations(moduleName, language)`
-- `blocks.localization.loadCloud(language, modules)`
-- `blocks.localization.keysByNames(...)`
-- `blocks.localization.t(key, fallback, options)`
-
-HTTP fallback:
-
-- Use `blocks.http.request("/service/v4/...")` only when no typed method exists.
-- Use `blocks.http.external(url, ...)` only for external URLs such as pre-signed uploads.
-
-Errors:
-
-- Every non-2xx response from `http.request`/`http.external` throws `BlocksApiError` (`status`, `statusText`, `body`). Catch it with `instanceof BlocksApiError` rather than assuming a generic `Error` shape.
-
-## Minimal Examples
-
-```ts
-const me = await blocks.iam.me();
-const schemas = await blocks.data.schemas.list({ pageNo: 1, pageSize: 20 });
-const rows = await blocks.data.collection("Students").list({ pageNo: 1, pageSize: 20 });
-await blocks.localization.load("en-US", ["common"]);
-const label = blocks.localization.t("save", "Save");
-```
-
-OIDC refresh with explicit client id:
-
-```ts
-await blocks.auth.oidc.refreshToken({
-  clientId: env.OIDC_CLIENT_ID,
-  refreshToken: session.refreshToken
-});
-```
-
-Embedded refresh:
-
-```ts
-await blocks.auth.refresh({
-  refreshToken: session.refreshToken
-});
-```
-
-## Check Before Finishing
-
-```bash
-npm test
-npm run lint
-npm pack --dry-run
-rg -n "v4[/\\]api|iam[/\\]v4[/\\]api|data[/\\]v4[/\\]api|localization[/\\]v4[/\\]api" src README.md AI_USAGE_GUIDE.md test
-```
-
-Only negative route-guard tests should match.
+# AI Usage Guide
+
+Use this file only for `@seliseblocks/client` app-code work. For full method details, read the source docstrings.
+
+Source refs:
+
+- Client setup: `src/client.ts`
+- Auth: `src/auth/auth-client.ts`
+- IAM: `src/iam/iam-client.ts`
+- Data: `src/data/data-client.ts`
+- Localization: `src/localization/localization-client.ts`
+- MFA: `src/mfa/mfa-client.ts`
+- HTTP/errors: `src/http/http-client.ts`, `src/http/errors.ts`
+
+## Non-Negotiable Rules
+
+- Configure `xBlocksKey`; SDK sends it as `x-blocks-key`.
+- Do not send `ProjectKey` or `projectKey`.
+- Do not add `/api` after `/v4`.
+- Valid route shapes: `/iam/v4/...`, `/data/v4/...`, `/localization/v4/...`.
+- SDK does not store tokens. App owns access token, refresh token, storage, and logout cleanup.
+- Frontend code must not contain client secrets.
+- Do not add impersonation, release deploy, schema/rules mutation, or localization authoring/admin APIs.
+
+## Create Client
+
+```ts
+import { createBlocksClient } from "@seliseblocks/client";
+
+export const blocks = createBlocksClient({
+  apiUrl: "https://api.seliseblocks.com",
+  xBlocksKey: env.BLOCKS_KEY,
+  accessToken: () => session.accessToken,
+  oidc: {
+    url: "https://iam.seliseblocks.com",
+    clientId: env.OIDC_CLIENT_ID,
+    redirectUri: env.OIDC_REDIRECT_URI ?? `${window.location.origin}/login/callback`
+  }
+});
+```
+
+Use `accessToken` only for the current token resolver. Do not add SDK token storage.
+Use a configured `redirectUri` when available; the current-origin `/login/callback` URL is only a browser fallback.
+
+## Auth Decision
+
+There are two auth flows.
+
+OIDC/hosted IAM flow:
+
+- Login: `blocks.auth.idp.initiate()`, `blocks.auth.idp.redirectToProvider()`, `blocks.auth.idp.callback(...)`
+- Refresh: `blocks.auth.oidc.refreshToken({ refreshToken })`
+- Refresh route: `POST /iam/v4/oidc/token`
+- Must send `client_id`; SDK uses `request.clientId` or configured `oidc.clientId`.
+- Do not manually build `oidc/authorize`.
+
+Embedded/app-owned flow:
+
+- Login: `blocks.auth.login(...)`
+- Social: `blocks.auth.socialInitiate(clientId, redirectUri)` (two positional strings), `blocks.auth.socialCallback(request)` (object)
+- Refresh: `blocks.auth.refresh({ refreshToken })`
+- Routes: `/iam/v4/auth/login`, `/iam/v4/auth/social/*`, `/iam/v4/auth/refresh`
+
+Shared auth methods for both flows:
+
+- `userInfo()`
+- `switchOrganization(...)`
+- `logout(...)`, `logoutAll(...)`
+- `signup(...)`, `recover(...)`, `resetPassword(...)`
+- `changePassword(...)`
+- `activate(...)`, `resendActivation(...)`, `validateActivation(...)`
+- `identityProviders.*`, `config.*`, `userCodes.*`, `clientCredentials.*` when app has permission
+- `accessToken()` - resolves the caller-owned bearer token configured on `createBlocksClient`.
+- `isAuthenticated()` - checks the session against IAM via `GET /iam/v4/auth/me`, returns a boolean from the raw response status. Prefer this over `userInfo()` for a true/false check, since a hosted-IdP session may live in a cookie with no local `accessToken` to inspect.
+
+## Service Map
+
+IAM:
+
+- `blocks.iam.me()`
+- `blocks.iam.users.*`
+- `blocks.iam.roles.*`
+- `blocks.iam.permissions.*`
+- `blocks.iam.resources.*`
+- `blocks.iam.organizations.*`
+- `blocks.iam.signupSettings.get()` / `.save(...)`
+
+MFA:
+
+- `blocks.mfa.config()` / `.saveConfig(...)` - tenant MFA policy
+- `blocks.mfa.totp.setup()` / `.verifySetup({ code })` - TOTP enrollment
+- `blocks.mfa.generate(...)` / `.resend(...)` / `.verify(...)` - OTP challenge flow
+- `blocks.mfa.setMethod({ mfaType })`, `.disable()`
+- `blocks.mfa.backupCodes.list()` / `.generate()` / `.use({ code, userId })`
+
+Data:
+
+- `blocks.data.schemas.*` for schema reads only
+- `blocks.data.validations.*` for validation reads
+- `blocks.data.collection("Name").list/get/create/update/delete`
+- `blocks.data.graphql(...)`
+- `blocks.data.files.*` for file/storage helpers
+- `blocks.data.directories.*` for directory create/get/update/delete/move
+- `blocks.data.objects.*` for browse/search/trash/shared/restore/share/access/inheritance
+- `blocks.data.utilities.*` for runtime utility helpers
+
+Localization:
+
+- `blocks.localization.languages()`
+- `blocks.localization.modules()`
+- `blocks.localization.languagesForCurrentTenant()`
+- `blocks.localization.modulesForCurrentTenant()`
+- `blocks.localization.translations(moduleName, language)`
+- `blocks.localization.load(language, modules)`
+- `blocks.localization.cloudTranslations(moduleName, language)`
+- `blocks.localization.loadCloud(language, modules)`
+- `blocks.localization.keysByNames(...)`
+- `blocks.localization.t(key, fallback, options)`
+
+HTTP fallback:
+
+- Use `blocks.http.request("/service/v4/...")` only when no typed method exists.
+- Use `blocks.http.external(url, ...)` only for external URLs such as pre-signed uploads.
+
+Errors:
+
+- Every non-2xx response from `http.request`/`http.external` throws `BlocksApiError` (`status`, `statusText`, `body`). Catch it with `instanceof BlocksApiError` rather than assuming a generic `Error` shape.
+
+## Minimal Examples
+
+```ts
+const me = await blocks.iam.me();
+const schemas = await blocks.data.schemas.list({ pageNo: 1, pageSize: 20 });
+const rows = await blocks.data.collection("Students").list({ pageNo: 1, pageSize: 20 });
+await blocks.localization.load("en-US", ["common"]);
+const label = blocks.localization.t("save", "Save");
+```
+
+OIDC refresh with explicit client id:
+
+```ts
+await blocks.auth.oidc.refreshToken({
+  clientId: env.OIDC_CLIENT_ID,
+  refreshToken: session.refreshToken
+});
+```
+
+Embedded refresh:
+
+```ts
+await blocks.auth.refresh({
+  refreshToken: session.refreshToken
+});
+```
+
+## Check Before Finishing
+
+```bash
+npm test
+npm run lint
+npm pack --dry-run
+rg -n "v4[/\\]api|iam[/\\]v4[/\\]api|data[/\\]v4[/\\]api|localization[/\\]v4[/\\]api" src README.md AI_USAGE_GUIDE.md test
+```
+
+Only negative route-guard tests should match.

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) SELISE Blocks
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.
+MIT License
+
+Copyright (c) SELISE Blocks
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,222 +1,222 @@
-# 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` 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
+```

package/dist/client.d.ts

@@ -42,6 +42,13 @@ export type BlocksClientConfig = {
      * Optional fetch-compatible function for tests, SSR, or custom runtimes.
      */
     fetch?: typeof fetch;
+    /**
+     * Caller-owned hook invoked at most once per request when a protected call comes back 401.
+     * Should resolve a fresh token (deduping concurrent callers itself, e.g. via a shared
+     * in-flight refresh promise) or `undefined` if the session cannot be recovered -- the SDK
+     * retries the request once with the returned token, or leaves the 401 to throw if none.
+     */
+    onUnauthorized?: () => Promise<string | undefined> | string | undefined;
     /**
      * Optional hosted IdP/OIDC browser-flow configuration.
      */
@@ -66,6 +73,7 @@ export type RequiredConfig = {
     accessToken?: string | (() => Promise<string | undefined> | string | undefined);
     apiUrl: string;
     appDomain?: string;
+    onUnauthorized?: () => Promise<string | undefined> | string | undefined;
     oidc?: BlocksOidcConfig & {
         redirectUri: string;
         scope: string;

package/dist/client.js

@@ -36,6 +36,7 @@ function normalizeConfig(config) {
         accessToken: config.accessToken,
         apiUrl: trimTrailingSlash(config.apiUrl),
         appDomain: config.appDomain,
+        onUnauthorized: config.onUnauthorized,
         oidc: config.oidc ? {
             ...config.oidc,
             redirectUri: config.oidc.redirectUri ?? browserRedirectUri(),

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/http/http-client.js

@@ -12,26 +12,38 @@ export class BlocksHttpClient {
     }
     async request(path, options = {}) {
         const url = buildUrl(this.config.apiUrl, path, options.query);
-        const headers = new Headers(options.headers);
         const rawBody = isBodyInit(options.body) ? options.body : undefined;
-        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");
+        const send = 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");
+            }
+            if (options.auth !== false) {
+                const token = accessTokenOverride ?? options.accessToken ?? await this.auth.accessToken();
+                if (token)
+                    headers.set("Authorization", `Bearer ${token}`);
+            }
+            return this.fetchImpl(url, {
+                body: rawBody ?? (options.body === undefined ? undefined : JSON.stringify(options.body)),
+                // IAM's hosted IdP flow sets the session as a Secure, httpOnly cookie by default;
+                // without this the browser never sends it back on subsequent Blocks API calls.
+                credentials: "include",
+                headers,
+                method: options.method ?? (options.body === undefined ? "GET" : "POST")
+            });
+        };
+        let response = await send();
+        // 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
+        // callers behind a single refresh) and retry exactly once with what it returns.
+        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);
         }
-        if (options.auth !== false) {
-            const token = options.accessToken ?? await this.auth.accessToken();
-            if (token)
-                headers.set("Authorization", `Bearer ${token}`);
-        }
-        const response = await this.fetchImpl(url, {
-            body: rawBody ?? (options.body === undefined ? undefined : JSON.stringify(options.body)),
-            // IAM's hosted IdP flow sets the session as a Secure, httpOnly cookie by default;
-            // without this the browser never sends it back on subsequent Blocks API calls.
-            credentials: "include",
-            headers,
-            method: options.method ?? (options.body === undefined ? "GET" : "POST")
-        });
         const body = await parseBody(response);
         if (!response.ok)
             throw new BlocksApiError(response.status, response.statusText, body);

package/package.json

@@ -1,48 +1,48 @@
-{
-  "name": "@seliseblocks/client",
-  "version": "0.1.5",
-  "description": "Framework-neutral TypeScript client SDK for SELISE Blocks frontend applications.",
-  "license": "MIT",
-  "type": "module",
-  "keywords": [
-    "selise",
-    "blocks",
-    "sdk",
-    "typescript",
-    "frontend"
-  ],
-  "main": "./dist/index.js",
-  "types": "./dist/index.d.ts",
-  "exports": {
-    ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js"
-    },
-    "./package.json": "./package.json"
-  },
-  "publishConfig": {
-    "access": "public"
-  },
-  "sideEffects": false,
-  "files": [
-    "dist",
-    "README.md",
-    "AI_USAGE_GUIDE.md",
-    "LICENSE"
-  ],
-  "scripts": {
-    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
-    "build": "npm run clean && tsc -p tsconfig.json",
-    "lint": "tsc -p tsconfig.json --noEmit",
-    "test": "npm run build && node --test test/*.test.mjs",
-    "prepack": "npm run build",
-    "prepublishOnly": "npm test"
-  },
-  "engines": {
-    "node": ">=20"
-  },
-  "devDependencies": {
-    "@types/node": "^22.0.0",
-    "typescript": "^5.5.0"
-  }
-}
+{
+  "name": "@seliseblocks/client",
+  "version": "0.1.6",
+  "description": "Framework-neutral TypeScript client SDK for SELISE Blocks frontend applications.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "selise",
+    "blocks",
+    "sdk",
+    "typescript",
+    "frontend"
+  ],
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "sideEffects": false,
+  "files": [
+    "dist",
+    "README.md",
+    "AI_USAGE_GUIDE.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\"",
+    "build": "npm run clean && tsc -p tsconfig.json",
+    "lint": "tsc -p tsconfig.json --noEmit",
+    "test": "npm run build && node --test test/*.test.mjs",
+    "prepack": "npm run build",
+    "prepublishOnly": "npm test"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.5.0"
+  }
+}