@seliseblocks/client 0.1.0-beta.0

package/AI_USAGE_GUIDE.md

@@ -0,0 +1,149 @@
+# 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`
+- 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(...)`, `blocks.auth.socialCallback(...)`
+- 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
+
+## Service Map
+
+IAM:
+
+- `blocks.iam.me()`
+- `blocks.iam.users.*`
+- `blocks.iam.roles.*`
+- `blocks.iam.permissions.*`
+- `blocks.iam.resources.*`
+- `blocks.iam.organizations.*`
+- `blocks.iam.signup.*`
+
+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.dms.*` for DMS file/folder helpers
+- `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.
+
+## 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

@@ -0,0 +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.

package/README.md

@@ -0,0 +1,161 @@
+# 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
+```
+
+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()`, `auth.socialCallback()`, 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.
+
+## Common Runtime Calls
+
+```ts
+const me = await blocks.iam.me();
+const orgs = await blocks.iam.organizations.my();
+const features = await blocks.iam.resources.features();
+```
+
+```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.dms.list({
+  configurationName: "default",
+  parentId: "root",
+  skip: 0,
+  take: 20
+});
+```
+
+```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.data`: schema reads, validation reads, GraphQL gateway execution, file/storage helpers, DMS file/folder helpers, runtime collection CRUD.
+- `blocks.localization`: tenant language/module discovery, UILM dictionary loading, selected key lookup, simple `t()` lookup.
+
+Professional class names are exported for advanced typing and adapters: `BlocksAuthenticationClient`, `BlocksIAMClient`, `BlocksDataClient`, and `BlocksLocalizationClient`.
+
+## 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/auth/auth-client.d.ts

@@ -0,0 +1,256 @@
+import type { RequiredConfig } 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 declare class BlocksAuthenticationClient {
+    private readonly clientConfig;
+    private readonly fetchImpl;
+    constructor(clientConfig: RequiredConfig, 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.
+     * How: call it before showing your login UI; it is public and still sends `x-blocks-key`.
+     */
+    loginOptions(): Promise<BlocksLoginOption[]>;
+    /**
+     * What: executes username/password login through `POST /iam/v4/auth/login`.
+     * Why: apps that own their login UI need a direct AuthController login call.
+     * How: pass IAM's expected login payload; the SDK returns IAM's response as-is and does not store tokens.
+     */
+    login(request: BlocksAuthLoginRequest): Promise<BlocksAuthResponse>;
+    /**
+     * What: starts social login through `GET /iam/v4/auth/social/initiate`.
+     * Why: custom login screens may offer social providers while keeping the app in charge of UI.
+     * How: provide the public browser client id and redirect URI, then follow IAM's returned social-login response.
+     */
+    socialInitiate(clientId: string, redirectUri: string): Promise<Record<string, unknown>>;
+    /**
+     * What: completes social login through `POST /iam/v4/auth/social/callback`.
+     * Why: the app receives the provider callback but IAM owns the token/session response contract.
+     * How: pass the callback payload your app received; store returned tokens in your app layer if IAM returns tokens.
+     */
+    socialCallback(request: BlocksSocialLoginRequest): Promise<BlocksAuthResponse>;
+    /**
+     * What: refreshes an AuthController token through `POST /iam/v4/auth/refresh`.
+     * Why: direct AuthController sessions refresh through AuthController instead of the OIDC token endpoint.
+     * How: pass the refresh payload your app owns; the SDK does not read or write token storage.
+     */
+    refresh(request?: BlocksRefreshRequest): Promise<BlocksAuthResponse>;
+    /**
+     * 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.
+     */
+    switchOrganization(request: BlocksSwitchOrganizationRequest): Promise<BlocksAuthResponse>;
+    /**
+     * What: reads OIDC-style current-user info through `GET /iam/v4/auth/me`.
+     * Why: apps may need profile claims from AuthController, separate from full IAM `iam.me()`.
+     * How: call after `accessToken` is available on `createBlocksClient`.
+     */
+    userInfo(): Promise<BlocksOidcUserInfo>;
+    /**
+     * What: logs out the current session through `POST /iam/v4/auth/logout`.
+     * Why: the app can ask IAM to invalidate the current session/refresh token while clearing its own local state.
+     * How: pass IAM's logout payload, commonly including `refreshToken`.
+     */
+    logout(request?: BlocksLogoutRequest): Promise<Record<string, unknown>>;
+    /**
+     * What: logs out all supported sessions through `POST /iam/v4/auth/logout-all`.
+     * Why: security-sensitive apps may offer a sign-out-everywhere action.
+     * How: pass IAM's logout-all payload and clear app-owned session state after success.
+     */
+    logoutAll(request?: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * What: registers a user through `POST /iam/v4/auth/signup`.
+     * Why: apps may own their signup page while IAM owns account creation rules.
+     * How: send IAM's signup payload and render IAM's response/errors directly.
+     */
+    signup(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * What: starts account/password recovery through `POST /iam/v4/auth/recover`.
+     * Why: apps need a public recovery entry point.
+     * How: pass the email or recovery payload IAM expects and return IAM's response to the UI.
+     */
+    recover(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * What: completes password reset through `POST /iam/v4/auth/reset-password`.
+     * Why: IAM owns reset-token validation and password policy enforcement.
+     * How: pass the reset payload from your reset form and show IAM's response/errors.
+     */
+    resetPassword(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * What: changes password through `POST /iam/v4/auth/change-password`.
+     * Why: authenticated users need an account-security action inside your app.
+     * How: pass IAM's change-password payload after an access token is available.
+     */
+    changePassword(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * What: activates an account through `POST /iam/v4/auth/activate`.
+     * Why: signup or invitation flows may require an activation step.
+     * How: pass the activation code/token payload IAM expects.
+     */
+    activate(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * What: requests another activation message through `POST /iam/v4/auth/resend-activation`.
+     * Why: users may need a new activation link/code.
+     * How: pass IAM's resend payload; this call uses the active bearer token when configured.
+     */
+    resendActivation(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    /**
+     * What: validates an activation payload through `POST /iam/v4/auth/validate-activation`.
+     * Why: apps can check activation state before committing the final activation UI step.
+     * How: pass the activation validation payload and render IAM's response.
+     */
+    validateActivation(request: Record<string, unknown>): Promise<Record<string, unknown>>;
+    readonly idp: {
+        /**
+         * What: starts the Blocks IAM IdP-controller browser/provider flow through `GET /iam/v4/idp/initiate`.
+         * Why: hosted login should rely on IAM's IdP controller instead of manually constructing `oidc/authorize`.
+         * How: pass optional `clientId`, `redirectUri`, or `forwardedTo`; otherwise the SDK uses `createBlocksClient().oidc` defaults and returns IAM's redirect response.
+         */
+        initiate: (request?: BlocksIdpInitiateRequest) => Promise<BlocksIdpInitiateResponse>;
+        /**
+         * What: starts hosted login and redirects the browser to IAM's returned provider URL.
+         * Why: browser apps often need one call that handles initiate plus navigation.
+         * How: call it from a login button handler; the function throws if IAM does not return `redirect_uri`.
+         */
+        redirectToProvider: (request?: BlocksIdpInitiateRequest) => Promise<void>;
+        /**
+         * What: completes the Blocks IAM IdP-controller callback through `GET /iam/v4/idp/callback`.
+         * Why: IAM owns the hosted callback contract and returns the auth response shape.
+         * How: pass `window.location.href` or an object with `code`, `state`, and optional OIDC error fields; store the returned tokens in your app layer if IAM returns tokens.
+         */
+        callback: (callback: string | BlocksIdpCallbackRequest) => Promise<BlocksAuthResponse>;
+        /**
+         * What: reads public UI configuration from `GET /iam/v4/idp/oidc-ui-config`.
+         * Why: hosted auth pages may need tenant login settings such as captcha or UI config before authentication.
+         * How: call before rendering hosted-auth support UI; the SDK returns IAM's response body without reshaping.
+         */
+        uiConfig: <T = Record<string, unknown>>() => Promise<T>;
+    };
+    readonly oidc: {
+        /**
+         * What: refreshes an OIDC-flow token through `POST /iam/v4/oidc/token` with `grant_type=refresh_token`.
+         * Why: hosted IdP login relies on IdPController for browser login, but token refresh still belongs to the OIDC token endpoint.
+         * How: pass the refresh token your app owns; the SDK always sends `client_id` from the request or client OIDC config and returns IAM's token response without storing it.
+         */
+        refreshToken: (request?: BlocksOidcRefreshRequest) => Promise<BlocksAuthResponse>;
+        /**
+         * What: requests a machine token through `POST /iam/v4/oidc/token` with `grant_type=client_credentials`.
+         * Why: backend jobs or trusted server-side adapters may need service access to Blocks APIs.
+         * How: call only outside public browser code because it requires `clientSecret`.
+         */
+        clientCredentials: (request: BlocksClientCredentialsRequest) => Promise<BlocksAuthResponse>;
+    };
+    readonly identityProviders: {
+        /**
+         * What: lists configured identity providers through `GET /iam/v4/auth/identity-providers`.
+         * Why: admin UI can show available IdP configurations.
+         * How: call with a type parameter when your app has a specific response model.
+         */
+        list: <T = BlocksAuthPassThroughResponse>() => Promise<T>;
+        /**
+         * What: reads one identity provider through `GET /iam/v4/auth/identity-providers/{id}`.
+         * Why: admin UI needs one record before edit/detail rendering.
+         * How: pass the IdP id from IAM.
+         */
+        get: <T = BlocksAuthPassThroughResponse>(id: string) => Promise<T>;
+        /**
+         * What: creates an identity provider through `POST /iam/v4/auth/identity-providers`.
+         * Why: authorized apps can configure tenant IdP options.
+         * How: pass IAM's IdP payload and receive IAM's response as-is.
+         */
+        create: <T = BlocksAuthPassThroughResponse>(request: Record<string, unknown>) => Promise<T>;
+        /**
+         * What: updates an identity provider through `PUT /iam/v4/auth/identity-providers/{id}`.
+         * Why: authorized apps can edit tenant IdP options.
+         * How: pass the IdP id and IAM's update payload.
+         */
+        update: <T = BlocksAuthPassThroughResponse>(id: string, request: Record<string, unknown>) => Promise<T>;
+        /**
+         * What: changes identity-provider status through `PATCH /iam/v4/auth/identity-providers/{id}/status`.
+         * Why: admin UI can enable or disable an IdP without editing the whole configuration.
+         * How: pass the IdP id and status payload IAM expects.
+         */
+        updateStatus: <T = BlocksAuthPassThroughResponse>(id: string, request: Record<string, unknown>) => Promise<T>;
+        /**
+         * What: deletes an identity provider through `DELETE /iam/v4/auth/identity-providers/{id}`.
+         * Why: admin UI can remove tenant IdP configuration.
+         * How: pass the IdP id; IAM decides whether deletion is allowed.
+         */
+        delete: <T = BlocksAuthPassThroughResponse>(id: string) => Promise<T>;
+    };
+    readonly config: {
+        /**
+         * What: reads auth configuration through `GET /iam/v4/auth/config`.
+         * Why: admin/settings UI can render current AuthController configuration.
+         * How: call after an authorized token is available.
+         */
+        get: <T = BlocksAuthPassThroughResponse>() => Promise<T>;
+        /**
+         * What: saves auth configuration through `POST /iam/v4/auth/config`.
+         * Why: admin/settings UI can update AuthController behavior.
+         * How: pass IAM's config payload and receive IAM's response as-is.
+         */
+        update: <T = BlocksAuthPassThroughResponse>(request: Record<string, unknown>) => Promise<T>;
+    };
+    readonly userCodes: {
+        /**
+         * What: lists user codes through `GET /iam/v4/auth/user-codes`.
+         * Why: apps using user-code auth/admin flows can show existing generated codes.
+         * How: call from an authorized surface.
+         */
+        list: <T = BlocksAuthPassThroughResponse>() => Promise<T>;
+        /**
+         * What: generates a user code through `POST /iam/v4/auth/user-codes`.
+         * Why: apps using user-code flows need IAM to create the code.
+         * How: pass IAM's generation payload.
+         */
+        generate: <T = BlocksAuthPassThroughResponse>(request: Record<string, unknown>) => Promise<T>;
+    };
+    readonly clientCredentials: {
+        /**
+         * What: lists client credentials through `GET /iam/v4/auth/client-credentials`.
+         * Why: authorized admin UIs can manage service credentials.
+         * How: call from a trusted/authorized management surface.
+         */
+        list: <T = BlocksAuthPassThroughResponse>() => Promise<T>;
+        /**
+         * What: creates or updates client credentials through `POST /iam/v4/auth/client-credentials`.
+         * Why: authorized admin UIs can provision service credentials.
+         * How: pass IAM's credential payload; do not expose generated secrets in public UI longer than necessary.
+         */
+        save: <T = BlocksAuthPassThroughResponse>(request: Record<string, unknown>) => Promise<T>;
+        /**
+         * What: deletes a client credential through `DELETE /iam/v4/auth/client-credentials/{id}`.
+         * Why: authorized admin UIs can revoke service credentials.
+         * How: pass the credential id from IAM.
+         */
+        delete: <T = BlocksAuthPassThroughResponse>(id: string) => Promise<T>;
+    };
+    /**
+     * What: resolves the caller-owned bearer token configured on `createBlocksClient`.
+     * Why: the SDK must not own browser sessions or token storage, but protected API calls still need the active token.
+     * How: provide `accessToken` as a string or callback in client config; call this when adapters need to inspect the resolved token.
+     */
+    accessToken(): Promise<string | undefined>;
+    /**
+     * What: checks whether `accessToken()` currently resolves a non-empty token.
+     * Why: apps may need a lightweight UI/session guard before rendering protected areas.
+     * How: use it as a convenience only; real authorization still comes from Blocks API responses and IAM permissions.
+     */
+    isAuthenticated(): Promise<boolean>;
+    /**
+     * What: sends a JSON Auth/IdPController request and returns the parsed response body.
+     * Why: auth endpoints can return protocol-shaped errors, so this layer intentionally does not reshape non-2xx bodies.
+     * How: SDK methods call this with the exact IAM route, method, query, and payload.
+     */
+    json<T>(path: string, options?: BlocksAuthJsonOptions): Promise<T>;
+    /**
+     * What: sends an `application/x-www-form-urlencoded` OIDC token request.
+     * Why: `/iam/v4/oidc/token` follows OAuth/OIDC form-post semantics rather than JSON body semantics.
+     * How: OIDC token helpers pass grant fields here; the response body is returned exactly as IAM sends it.
+     */
+    form<T>(path: string, form: Record<string, string | undefined>): Promise<T>;
+    private raw;
+    private get oidcDefaults();
+}