@seliseblocks/client 0.1.5 → 0.2.0

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

@@ -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);
@@ -49,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
@@ -59,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)
@@ -73,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,6 +1,6 @@
 {
   "name": "@seliseblocks/client",
-  "version": "0.1.5",
+  "version": "0.2.0",
   "description": "Framework-neutral TypeScript client SDK for SELISE Blocks frontend applications.",
   "license": "MIT",
   "type": "module",
@@ -11,6 +11,16 @@
     "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": {
@@ -27,7 +37,8 @@
   "files": [
     "dist",
     "README.md",
-    "AI_USAGE_GUIDE.md",
+    "CHANGELOG.md",
+    "AGENT_GUIDE.md",
     "LICENSE"
   ],
   "scripts": {