@seliseblocks/client 0.1.6 → 0.2.0

package/{AI_USAGE_GUIDE.md → AGENT_GUIDE.md}

@@ -1,4 +1,4 @@
-# AI Usage Guide
+# Blocks Client Guide for AI Agents
 
 Use this file only for `@seliseblocks/client` app-code work. For full method details, read the source docstrings.
 
@@ -159,7 +159,7 @@ await blocks.auth.refresh({
 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
+rg -n "v4[/\\]api|iam[/\\]v4[/\\]api|data[/\\]v4[/\\]api|localization[/\\]v4[/\\]api" src README.md AGENT_GUIDE.md test
 ```
 
 Only negative route-guard tests should match.

package/CHANGELOG.md

@@ -0,0 +1,57 @@
+# Changelog
+
+All notable changes to `@seliseblocks/client`.
+
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+Versions before 0.2.0 were released without a changelog; their history is in the
+repository's git log.
+
+## 0.2.0
+
+### Breaking
+
+- `blocks.config` no longer carries `accessToken` or `onUnauthorized`. Both are
+  callables that reach a live session, and this package's stated boundary is that
+  it never becomes somewhere to read one from. Use
+  `await blocks.auth.accessToken()` for the token; the hook stays available to
+  the client internally. Everything else on `config` (`apiUrl`, `xBlocksKey`,
+  `appDomain`, `oidc`) is unchanged, and its type is now `BlocksPublicConfig`.
+- `http.request()` refuses an absolute URL whose origin is not the configured
+  `apiUrl`. It attaches the bearer token, `x-blocks-key`, and cookies, so a
+  foreign origin would have received a live session. `http.external(url)` is the
+  path for third-party URLs and sends no Blocks credentials. An absolute URL on
+  the configured API still works.
+
+### Added
+
+- Types that were reachable in the public surface but not importable by name are
+  now exported: `BlocksHttpClient`, `BlocksDataSchema`,
+  `BlocksDataCollectionOptions`, `BlocksDataGetOptions`,
+  `BlocksDataDeleteOptions`, `BlocksAuthJsonOptions`,
+  `BlocksExternalRequestOptions`, and `BlocksPublicConfig`.
+
+### Changed
+
+- `RequiredConfig` is renamed `BlocksResolvedConfig`, matching every other
+  exported name. `RequiredConfig` remains as a deprecated alias.
+- Documented the IAM enums the typings previously called opaque:
+  `mfaType`/`UserMfaType` (0 None, 1 TOTP, 2 Email, 3 Sms, 4 WhatsApp — only 1
+  and 2 have a provider, and `setMethod` turns MFA *off* for any other value)
+  and the notifier sort order (1 CreatedTime newest-first, 2 ReadStatus; any
+  other value, including an omitted 0, returns an empty list).
+
+### Fixed
+
+- A non-2xx response whose body is not valid JSON despite an
+  `application/json` content type now throws `BlocksApiError` carrying the status
+  and the raw text. It previously threw a bare `SyntaxError` before the status
+  was ever checked, which lost the status and broke the documented contract that
+  every non-2xx response surfaces as a `BlocksApiError` — the case that matters
+  most, since a proxy or WAF error page is exactly what arrives mislabelled.
+- The README's MFA examples were stranded under the Auth heading with no heading
+  of their own.
+
+### Package metadata
+
+- Added `repository`, `homepage`, `bugs`, and `author`.
+- `LICENSE` now matches the repository's copyright line.

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) 2026 SELISE Digital Platforms
+
+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

@@ -2,11 +2,11 @@
 
 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.
+[`@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 [AI_USAGE_GUIDE.md](AI_USAGE_GUIDE.md).
+For AI agents and automation, see [AGENT_GUIDE.md](AGENT_GUIDE.md).
 
 ## Install
 
@@ -37,6 +37,17 @@ const blocks = createBlocksClient({
 
 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
@@ -75,6 +86,13 @@ Other auth APIs, such as user info, organization switch, logout, signup, recover
 
 `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();
@@ -177,17 +195,11 @@ const selectedKeys = await blocks.localization.keysByNames({
 
 ## 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`:
+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.mfa`, `blocks.mail`, and `blocks.notifier`.
+
+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`. 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 {

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.

package/dist/client.d.ts

@@ -58,9 +58,18 @@ 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;
@@ -69,7 +78,12 @@ export type BlocksClient = {
     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,6 +94,8 @@ 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.

package/dist/client.js

@@ -15,9 +15,10 @@ 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),

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

@@ -1,11 +1,11 @@
 import { BlocksAuthenticationClient } from "../auth/auth-client.js";
-import { RequiredConfig } from "../client.js";
+import { BlocksResolvedConfig } from "../client.js";
 import { BlocksExternalRequestOptions, BlocksRequestOptions } from "../types.js";
 export declare class BlocksHttpClient {
     private readonly config;
     private readonly auth;
     private readonly fetchImpl;
-    constructor(config: RequiredConfig, auth: BlocksAuthenticationClient, fetchImpl?: typeof fetch);
+    constructor(config: BlocksResolvedConfig, auth: BlocksAuthenticationClient, fetchImpl?: typeof fetch);
     request<T>(path: string, options?: BlocksRequestOptions): Promise<T>;
     external<T = unknown>(url: string, options?: BlocksExternalRequestOptions): Promise<T>;
 }

package/dist/http/http-client.js

@@ -61,6 +61,23 @@ export class BlocksHttpClient {
         return body;
     }
 }
+/**
+ * `request` attaches the caller's bearer token, `x-blocks-key`, and
+ * `credentials: "include"`, so it must only ever reach the configured Blocks
+ * API. An absolute URL is still accepted -- callers legitimately pass a full
+ * API URL -- but one pointing somewhere else would hand a live session to a
+ * third party, so it is refused with a pointer to `external`, which sends no
+ * Blocks credentials by design.
+ */
+function sameOriginOnly(path, baseUrl) {
+    const target = new URL(path);
+    const base = new URL(`${baseUrl}/`);
+    if (target.origin !== base.origin) {
+        throw new Error(`Refusing to send Blocks credentials to ${target.origin}: it is not the configured apiUrl (${base.origin}). `
+            + "Use blocks.http.external(url) for third-party URLs such as a pre-signed storage upload.");
+    }
+    return target;
+}
 function isBodyInit(value) {
     return typeof Blob !== "undefined" && value instanceof Blob
         || typeof FormData !== "undefined" && value instanceof FormData
@@ -71,7 +88,7 @@ function isBodyInit(value) {
 }
 function buildUrl(baseUrl, path, query) {
     const url = /^https?:\/\//i.test(path)
-        ? new URL(path)
+        ? sameOriginOnly(path, baseUrl)
         : new URL(path.replace(/^\/+/, ""), `${baseUrl}/`);
     for (const [key, value] of Object.entries(query ?? {})) {
         if (value !== undefined)
@@ -85,9 +102,13 @@ async function parseBody(response) {
     const text = await response.text();
     if (!text)
         return undefined;
-    const contentType = response.headers.get("content-type") ?? "";
-    if (contentType.includes("application/json"))
-        return JSON.parse(text);
+    // Parsing is best-effort for every content type, including a declared
+    // application/json. A proxy, WAF, or load balancer in front of the API can
+    // answer with an HTML error page while still claiming JSON; throwing a raw
+    // SyntaxError there would lose the HTTP status entirely and break the
+    // documented contract that a non-2xx response always surfaces as a
+    // BlocksApiError. Returning the raw text keeps the status and hands the
+    // caller the body it actually got.
     try {
         return JSON.parse(text);
     }

package/dist/index.d.ts

@@ -1,17 +1,20 @@
 export { createBlocksClient } from "./client.js";
 export { BlocksAuthenticationClient } from "./auth/auth-client.js";
 export { BlocksDataClient } from "./data/data-client.js";
-export type { BlocksClient, BlocksClientConfig, BlocksOidcConfig } from "./client.js";
+export type { BlocksClient, BlocksClientConfig, BlocksOidcConfig, BlocksPublicConfig, BlocksResolvedConfig, 
+/** @deprecated Renamed to `BlocksResolvedConfig`. */
+RequiredConfig } from "./client.js";
 export { BlocksApiError } from "./http/errors.js";
+export type { BlocksHttpClient } from "./http/http-client.js";
 export { BlocksIAMClient } from "./iam/iam-client.js";
 export { BlocksLocalizationClient } from "./localization/localization-client.js";
 export { BlocksMailClient } from "./mail/mail-client.js";
 export { BlocksMfaClient } from "./mfa/mfa-client.js";
 export { BlocksNotifierClient } from "./notifier/notifier-client.js";
-export type { BlocksAuthPassThroughResponse, BlocksAuthResponse, BlocksClientCredentialsRequest, BlocksAuthLoginRequest, BlocksIdpCallbackRequest, BlocksIdpInitiateRequest, BlocksIdpInitiateResponse, BlocksLoginOption, BlocksLogoutRequest, BlocksOidcRefreshRequest, BlocksOidcUserInfo, BlocksRefreshRequest, BlocksSocialLoginRequest, BlocksSwitchOrganizationRequest } from "./auth/auth-client.js";
-export type { BlocksRequestOptions } from "./types.js";
+export type { BlocksAuthJsonOptions, BlocksAuthPassThroughResponse, BlocksAuthResponse, BlocksClientCredentialsRequest, BlocksAuthLoginRequest, BlocksIdpCallbackRequest, BlocksIdpInitiateRequest, BlocksIdpInitiateResponse, BlocksLoginOption, BlocksLogoutRequest, BlocksOidcRefreshRequest, BlocksOidcUserInfo, BlocksRefreshRequest, BlocksSocialLoginRequest, BlocksSwitchOrganizationRequest } from "./auth/auth-client.js";
+export type { BlocksExternalRequestOptions, BlocksRequestOptions } from "./types.js";
 export type { BlocksBaseResponse, BlocksGetMyOrganizationsResponse, BlocksGetOrganizationResponse, BlocksGetOrganizationsResponse, BlocksGetPermissionResponse, BlocksGetPermissionsResponse, BlocksGetRoleResponse, BlocksGetRolesResponse, BlocksGetUserResponse, BlocksGetUsersResponse, BlocksIamListRequest, BlocksMeResponse, BlocksOrganization, BlocksPermission, BlocksQueryListResponse, BlocksQueryResponse, BlocksRole, BlocksUser } from "./iam/types.js";
-export type { BlocksDataCollection, BlocksDataListOptions, BlocksDirectoryCreateRequest, BlocksDirectoryDeleteRequest, BlocksDirectoryMoveRequest, BlocksDirectoryUpdateRequest, BlocksFileCopyRequest, BlocksFileCreateVersionRequest, BlocksFileDeleteRequest, BlocksFileGetOptions, BlocksFileInfoListRequest, BlocksFileListRequest, BlocksFileMoveRequest, BlocksFileRenameRequest, BlocksFileUpdateAdditionalInfoRequest, BlocksFileUploadRequest, BlocksFileVersionsRequest, BlocksGraphqlRequest, BlocksLocalStorageUploadRequest, BlocksPagedResult, BlocksRegexGenerateRequest, BlocksSchemaFieldValidationOptions, BlocksSchemaListOptions, BlocksSchemaValidationListOptions, BlocksStorageAccessPolicyRequest, BlocksStorageEffect, BlocksStorageObject, BlocksStorageObjectListRequest, BlocksStorageObjectPageRequest, BlocksStorageObjectSearchRequest, BlocksStorageObjectsResponse, BlocksStorageObjectType, BlocksStoragePermission, BlocksStoragePermissionFlags, BlocksStoragePrincipalType, BlocksStorageResourceRequest, BlocksStorageResourceType, BlocksStorageRevokeAccessRequest, BlocksStorageShareRequest, BlocksStorageToggleInheritanceRequest, BlocksUploadToUrlRequest } from "./data/types.js";
+export type { BlocksDataCollection, BlocksDataCollectionOptions, BlocksDataDeleteOptions, BlocksDataGetOptions, BlocksDataListOptions, BlocksDataSchema, BlocksDirectoryCreateRequest, BlocksDirectoryDeleteRequest, BlocksDirectoryMoveRequest, BlocksDirectoryUpdateRequest, BlocksFileCopyRequest, BlocksFileCreateVersionRequest, BlocksFileDeleteRequest, BlocksFileGetOptions, BlocksFileInfoListRequest, BlocksFileListRequest, BlocksFileMoveRequest, BlocksFileRenameRequest, BlocksFileUpdateAdditionalInfoRequest, BlocksFileUploadRequest, BlocksFileVersionsRequest, BlocksGraphqlRequest, BlocksLocalStorageUploadRequest, BlocksPagedResult, BlocksRegexGenerateRequest, BlocksSchemaFieldValidationOptions, BlocksSchemaListOptions, BlocksSchemaValidationListOptions, BlocksStorageAccessPolicyRequest, BlocksStorageEffect, BlocksStorageObject, BlocksStorageObjectListRequest, BlocksStorageObjectPageRequest, BlocksStorageObjectSearchRequest, BlocksStorageObjectsResponse, BlocksStorageObjectType, BlocksStoragePermission, BlocksStoragePermissionFlags, BlocksStoragePrincipalType, BlocksStorageResourceRequest, BlocksStorageResourceType, BlocksStorageRevokeAccessRequest, BlocksStorageShareRequest, BlocksStorageToggleInheritanceRequest, BlocksUploadToUrlRequest } from "./data/types.js";
 export type { BlocksLocalizationDictionary, BlocksLocalizationKey, BlocksLocalizationKeyResource, BlocksLocalizationKeysByNamesRequest, BlocksLocalizationKeysByNamesResponse, BlocksLocalizationLanguage, BlocksLocalizationModule, BlocksLocalizationTranslationOptions } from "./localization/types.js";
 export type { BlocksMfaBackupCodeUseRequest, BlocksMfaConfig, BlocksMfaConfigSaveRequest, BlocksMfaGenerateRequest, BlocksMfaPassThroughResponse, BlocksMfaResendRequest, BlocksMfaSetMethodRequest, BlocksMfaVerifyRequest, BlocksMfaVerifyTotpSetupRequest } from "./mfa/types.js";
 export type { BlocksMailPassThroughResponse, BlocksSendMailRequest, BlocksSendMailToAnyRequest } from "./mail/types.js";

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

@@ -58,6 +58,8 @@ export declare class BlocksMfaClient {
      * What: sets the signed-in user's active MFA method through `PUT /iam/v4/mfa/method`.
      * Why: users who have enrolled more than one method need to switch which one is active.
      * How: pass the `mfaType` to activate; enroll it first (e.g. via `totp.setup`/`verifySetup`) if it isn't already.
+       * Careful: IAM only branches on TOTP (1) and Email (2) here -- every other value falls through to its
+       * disable path and turns the user's MFA off. Use `disable()` when that is the intent.
      */
     setMethod(request: BlocksMfaSetMethodRequest): Promise<BlocksMfaPassThroughResponse>;
     /**

package/dist/mfa/mfa-client.js

@@ -69,6 +69,8 @@ export class BlocksMfaClient {
      * What: sets the signed-in user's active MFA method through `PUT /iam/v4/mfa/method`.
      * Why: users who have enrolled more than one method need to switch which one is active.
      * How: pass the `mfaType` to activate; enroll it first (e.g. via `totp.setup`/`verifySetup`) if it isn't already.
+       * Careful: IAM only branches on TOTP (1) and Email (2) here -- every other value falls through to its
+       * disable path and turns the user's MFA off. Use `disable()` when that is the intent.
      */
     setMethod(request) {
         return this.http.request(`${MFA_API}/method`, {

package/dist/mfa/types.d.ts

@@ -21,7 +21,7 @@ export type BlocksMfaConfigSaveRequest = Record<string, unknown> & {
     userMfaType?: number[];
 };
 export type BlocksMfaGenerateRequest = {
-    /** IAM-defined numeric MFA method (its enum names aren't in the swagger contract -- treat as opaque). */
+    /** IAM's UserMfaType: 0 None, 1 TOTP, 2 Email, 3 Sms, 4 WhatsApp. Only 1 and 2 have a provider. */
     mfaType: number;
     sendPhoneNumberAsEmailDomain?: string;
 };
@@ -30,6 +30,7 @@ export type BlocksMfaResendRequest = {
     sendPhoneNumberAsEmailDomain?: string;
 };
 export type BlocksMfaVerifyRequest = {
+    /** Same UserMfaType enum as `mfaType`: the method that issued this challenge (1 TOTP, 2 Email). */
     authType: number;
     isFromTokenCall?: boolean;
     mfaId: string;

package/dist/notifier/types.d.ts

@@ -16,7 +16,7 @@ export type BlocksNotifyRequest = {
     userIds?: string[];
 };
 export type BlocksGetUnreadNotificationsBySubscriptionFilterRequest = {
-    /** IAM/Notifier-defined order enum (its meanings aren't in the swagger contract -- treat as opaque). */
+    /** 1 = CreatedTime (newest first), 2 = ReadStatus. Any other value (including an omitted 0) returns an empty list. */
     orderBy?: 1 | 2;
     subscriptionFilterData?: BlocksNotifierSubscriptionFilter;
     userId?: string;

package/package.json

@@ -1,48 +1,59 @@
-{
-  "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"
-  }
-}
+{
+  "name": "@seliseblocks/client",
+  "version": "0.2.0",
+  "description": "Framework-neutral TypeScript client SDK for SELISE Blocks frontend applications.",
+  "license": "MIT",
+  "type": "module",
+  "keywords": [
+    "selise",
+    "blocks",
+    "sdk",
+    "typescript",
+    "frontend"
+  ],
+  "homepage": "https://github.com/SELISEdigitalplatforms/blocks-cli/tree/main/blocks-client#readme",
+  "bugs": {
+    "url": "https://github.com/SELISEdigitalplatforms/blocks-cli/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SELISEdigitalplatforms/blocks-cli.git",
+    "directory": "blocks-client"
+  },
+  "author": "SELISE Digital Platforms",
+  "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",
+    "CHANGELOG.md",
+    "AGENT_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"
+  }
+}