@seliseblocks/client 0.1.2 → 0.1.3

package/AI_USAGE_GUIDE.md

@@ -9,6 +9,7 @@ Source refs:
 - 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
@@ -56,7 +57,7 @@ OIDC/hosted IAM flow:
 Embedded/app-owned flow:
 
 - Login: `blocks.auth.login(...)`
-- Social: `blocks.auth.socialInitiate(...)`, `blocks.auth.socialCallback(...)`
+- 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`
 
@@ -69,6 +70,8 @@ Shared auth methods for both flows:
 - `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
 
@@ -80,7 +83,15 @@ IAM:
 - `blocks.iam.permissions.*`
 - `blocks.iam.resources.*`
 - `blocks.iam.organizations.*`
-- `blocks.iam.signup.*`
+- `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:
 
@@ -110,6 +121,10 @@ 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

package/README.md

@@ -56,7 +56,7 @@ const refreshed = await blocks.auth.oidc.refreshToken({
 });
 ```
 
-Embedded/app-owned login UI uses AuthController methods directly on `auth`: `auth.login()`, `auth.socialInitiate()`, `auth.socialCallback()`, and `auth.refresh()`.
+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({
@@ -73,6 +73,48 @@ Other auth APIs, such as user info, organization switch, logout, signup, recover
 
 `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
@@ -132,11 +174,24 @@ const selectedKeys = await blocks.localization.keysByNames({
 - `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`: current user, users, roles, permissions, resources, organizations, signup settings (`blocks.iam.signupSettings`).
 - `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.
+- `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`, and `BlocksLocalizationClient`.
+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
 

package/dist/client.d.ts

@@ -3,7 +3,9 @@ import { BlocksDataClient } from "./data/data-client.js";
 import { BlocksHttpClient } from "./http/http-client.js";
 import { BlocksIAMClient } from "./iam/iam-client.js";
 import { BlocksLocalizationClient } from "./localization/localization-client.js";
+import { BlocksMailClient } from "./mail/mail-client.js";
 import { BlocksMfaClient } from "./mfa/mfa-client.js";
+import { BlocksNotifierClient } from "./notifier/notifier-client.js";
 export type BlocksOidcConfig = {
     /**
      * Public browser OIDC client id used by Blocks IAM IdpController and refresh-token calls.
@@ -56,7 +58,9 @@ export type BlocksClient = {
     http: BlocksHttpClient;
     iam: BlocksIAMClient;
     localization: BlocksLocalizationClient;
+    mail: BlocksMailClient;
     mfa: BlocksMfaClient;
+    notifier: BlocksNotifierClient;
 };
 export type RequiredConfig = {
     accessToken?: string | (() => Promise<string | undefined> | string | undefined);

package/dist/client.js

@@ -3,7 +3,9 @@ import { BlocksDataClient } from "./data/data-client.js";
 import { BlocksHttpClient } from "./http/http-client.js";
 import { BlocksIAMClient } from "./iam/iam-client.js";
 import { BlocksLocalizationClient } from "./localization/localization-client.js";
+import { BlocksMailClient } from "./mail/mail-client.js";
 import { BlocksMfaClient } from "./mfa/mfa-client.js";
+import { BlocksNotifierClient } from "./notifier/notifier-client.js";
 /**
  * What: creates a framework-neutral Blocks SDK instance for one tenant/app runtime.
  * Why: frontend code needs a single configured entry point for IAM, Auth, Data, and Localization APIs.
@@ -20,7 +22,9 @@ export function createBlocksClient(config) {
         http,
         iam: new BlocksIAMClient(http),
         localization: new BlocksLocalizationClient(http),
-        mfa: new BlocksMfaClient(http)
+        mail: new BlocksMailClient(http),
+        mfa: new BlocksMfaClient(http),
+        notifier: new BlocksNotifierClient(http)
     };
 }
 function normalizeConfig(config) {

package/dist/index.d.ts

@@ -5,10 +5,14 @@ export type { BlocksClient, BlocksClientConfig, BlocksOidcConfig } from "./clien
 export { BlocksApiError } from "./http/errors.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 { 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, BlocksDmsCreateFolderRequest, BlocksDmsListRequest, BlocksDmsMetaDataValue, BlocksDmsUploadItem, BlocksDmsUploadRequest, BlocksFileDeleteRequest, BlocksFileGetOptions, BlocksFileInfoListRequest, BlocksFileListRequest, BlocksFileUpdateAdditionalInfoRequest, BlocksFileUploadRequest, BlocksFolderDeleteRequest, BlocksGraphqlRequest, BlocksLocalStorageUploadRequest, BlocksPagedResult, BlocksRegexGenerateRequest, BlocksSchemaFieldValidationOptions, BlocksSchemaListOptions, BlocksSchemaValidationListOptions, BlocksUploadToUrlRequest } from "./data/types.js";
 export type { BlocksLocalizationDictionary, BlocksLocalizationKey, BlocksLocalizationKeyResource, BlocksLocalizationKeysByNamesRequest, BlocksLocalizationKeysByNamesResponse, BlocksLocalizationLanguage, BlocksLocalizationModule, BlocksLocalizationTranslationOptions } from "./localization/types.js";
-export type { BlocksMfaBackupCodeUseRequest, BlocksMfaConfig, BlocksMfaGenerateRequest, BlocksMfaPassThroughResponse, BlocksMfaResendRequest, BlocksMfaSetMethodRequest, BlocksMfaVerifyRequest, BlocksMfaVerifyTotpSetupRequest } from "./mfa/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";
+export type { BlocksGetNotificationsOptions, BlocksGetNotificationsResponse, BlocksGetUnreadNotificationsBySubscriptionFilterRequest, BlocksMarkNotificationAsReadRequest, BlocksNotifierPassThroughResponse, BlocksNotifierSubscriptionFilter, BlocksNotifyRequest, BlocksOfflineNotification } from "./notifier/types.js";

package/dist/index.js

@@ -4,4 +4,6 @@ export { BlocksDataClient } from "./data/data-client.js";
 export { BlocksApiError } from "./http/errors.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";

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

@@ -0,0 +1,23 @@
+import { BlocksHttpClient } from "../http/http-client.js";
+import { BlocksMailPassThroughResponse, BlocksSendMailRequest, BlocksSendMailToAnyRequest } from "./types.js";
+/**
+ * Mail sending surface: fires a purpose/language-templated email through the tenant's
+ * configured mail provider. Mail server/template/mailbox management (Mail/Save, Mail/Get,
+ * templates, mailbox reads) is a CLI/admin concern and is not exposed here.
+ */
+export declare class BlocksMailClient {
+    private readonly http;
+    constructor(http: BlocksHttpClient);
+    /**
+     * What: sends an email through `POST /logic/v4/Mail/Send` using the tenant's default mail configuration.
+     * Why: app code needs to trigger transactional email (welcome, password reset, alerts) without managing SMTP directly.
+     * How: pass recipients plus `purpose`/`language` to select the right template, and `subjectDataContext`/`bodyDataContext` for placeholder values.
+     */
+    send(request: BlocksSendMailRequest): Promise<BlocksMailPassThroughResponse>;
+    /**
+     * What: sends an email through `POST /logic/v4/Mail/SendToAny`.
+     * Why: some sends need a provider-routing hint the default `send` doesn't take, such as marking a test send.
+     * How: same fields as `send`, plus `isTestMail`.
+     */
+    sendToAny(request: BlocksSendMailToAnyRequest): Promise<BlocksMailPassThroughResponse>;
+}

package/dist/mail/mail-client.js

@@ -0,0 +1,28 @@
+const MAIL_API = "/logic/v4/Mail";
+/**
+ * Mail sending surface: fires a purpose/language-templated email through the tenant's
+ * configured mail provider. Mail server/template/mailbox management (Mail/Save, Mail/Get,
+ * templates, mailbox reads) is a CLI/admin concern and is not exposed here.
+ */
+export class BlocksMailClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * What: sends an email through `POST /logic/v4/Mail/Send` using the tenant's default mail configuration.
+     * Why: app code needs to trigger transactional email (welcome, password reset, alerts) without managing SMTP directly.
+     * How: pass recipients plus `purpose`/`language` to select the right template, and `subjectDataContext`/`bodyDataContext` for placeholder values.
+     */
+    send(request) {
+        return this.http.request(`${MAIL_API}/Send`, { body: request });
+    }
+    /**
+     * What: sends an email through `POST /logic/v4/Mail/SendToAny`.
+     * Why: some sends need a provider-routing hint the default `send` doesn't take, such as marking a test send.
+     * How: same fields as `send`, plus `isTestMail`.
+     */
+    sendToAny(request) {
+        return this.http.request(`${MAIL_API}/SendToAny`, { body: request });
+    }
+}

package/dist/mail/types.d.ts

@@ -0,0 +1,18 @@
+export type BlocksSendMailRequest = {
+    attachments?: string[];
+    bcc?: string[];
+    bodyDataContext?: Record<string, string>;
+    cc?: string[];
+    language?: string;
+    /** Defaults to the tenant's `x-blocks-key` on the server side when omitted. */
+    projectKey?: string;
+    purpose?: string;
+    replyTo?: string[];
+    sendPhoneNumberAsEmail?: boolean;
+    subjectDataContext?: Record<string, string>;
+    to?: string[];
+};
+export type BlocksSendMailToAnyRequest = BlocksSendMailRequest & {
+    isTestMail?: boolean;
+};
+export type BlocksMailPassThroughResponse = Record<string, unknown>;

package/dist/mail/types.js

@@ -0,0 +1 @@
+export {};

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

@@ -1,10 +1,10 @@
 import { BlocksHttpClient } from "../http/http-client.js";
-import { BlocksMfaBackupCodeUseRequest, BlocksMfaConfig, BlocksMfaGenerateRequest, BlocksMfaPassThroughResponse, BlocksMfaResendRequest, BlocksMfaSetMethodRequest, BlocksMfaVerifyRequest, BlocksMfaVerifyTotpSetupRequest } from "./types.js";
+import { BlocksMfaBackupCodeUseRequest, BlocksMfaConfig, BlocksMfaConfigSaveRequest, BlocksMfaGenerateRequest, BlocksMfaPassThroughResponse, BlocksMfaResendRequest, BlocksMfaSetMethodRequest, BlocksMfaVerifyRequest, BlocksMfaVerifyTotpSetupRequest } from "./types.js";
 /**
- * Consumer-facing MFA surface: enroll, verify, switch, or disable the signed-in user's own MFA,
- * and manage their own backup codes. Tenant-wide MFA policy (`POST /iam/v4/mfa/config`) is
- * deliberately not exposed here -- that's an admin/tenant-settings action, not a user self-service
- * flow, the same distinction the SDK already draws for `identityProviders` admin methods.
+ * MFA surface: enroll, verify, switch, or disable the signed-in user's own MFA and manage
+ * their own backup codes, plus `saveConfig` for the tenant-wide MFA policy. Like
+ * `identityProviders`/`config`/`clientCredentials` on `BlocksAuthenticationClient`, `saveConfig`
+ * is an admin/tenant-settings action -- IAM enforces the required role, the SDK does not gate it.
  */
 export declare class BlocksMfaClient {
     private readonly http;
@@ -15,6 +15,13 @@ export declare class BlocksMfaClient {
      * How: call with an authorized token; the SDK returns IAM's policy shape as-is.
      */
     config(): Promise<BlocksMfaConfig>;
+    /**
+     * What: saves the tenant's MFA policy through `POST /iam/v4/mfa/config`.
+     * Why: tenant admin/settings screens need to turn MFA on/off, require it for specific roles,
+     * or configure backup codes -- this is not a user self-service action.
+     * How: pass IAM's full config payload with an authorized, sufficiently-privileged token.
+     */
+    saveConfig(request: BlocksMfaConfigSaveRequest): Promise<BlocksMfaPassThroughResponse>;
     readonly totp: {
         /**
          * What: starts TOTP enrollment through `POST /iam/v4/mfa/totp/setup`.

package/dist/mfa/mfa-client.js

@@ -1,9 +1,9 @@
 const MFA_API = "/iam/v4/mfa";
 /**
- * Consumer-facing MFA surface: enroll, verify, switch, or disable the signed-in user's own MFA,
- * and manage their own backup codes. Tenant-wide MFA policy (`POST /iam/v4/mfa/config`) is
- * deliberately not exposed here -- that's an admin/tenant-settings action, not a user self-service
- * flow, the same distinction the SDK already draws for `identityProviders` admin methods.
+ * MFA surface: enroll, verify, switch, or disable the signed-in user's own MFA and manage
+ * their own backup codes, plus `saveConfig` for the tenant-wide MFA policy. Like
+ * `identityProviders`/`config`/`clientCredentials` on `BlocksAuthenticationClient`, `saveConfig`
+ * is an admin/tenant-settings action -- IAM enforces the required role, the SDK does not gate it.
  */
 export class BlocksMfaClient {
     http;
@@ -18,6 +18,15 @@ export class BlocksMfaClient {
     config() {
         return this.http.request(`${MFA_API}/config`);
     }
+    /**
+     * What: saves the tenant's MFA policy through `POST /iam/v4/mfa/config`.
+     * Why: tenant admin/settings screens need to turn MFA on/off, require it for specific roles,
+     * or configure backup codes -- this is not a user self-service action.
+     * How: pass IAM's full config payload with an authorized, sufficiently-privileged token.
+     */
+    saveConfig(request) {
+        return this.http.request(`${MFA_API}/config`, { body: request });
+    }
     totp = {
         /**
          * What: starts TOTP enrollment through `POST /iam/v4/mfa/totp/setup`.

package/dist/mfa/types.d.ts

@@ -6,6 +6,20 @@ export type BlocksMfaConfig = Record<string, unknown> & {
     requireMfaForAllUsers?: boolean;
     userMfaType?: number[];
 };
+export type BlocksMfaConfigSaveRequest = Record<string, unknown> & {
+    allowBackupCodes?: boolean;
+    allowUserOptOut?: boolean;
+    backupCodesCount?: number;
+    enableMfa?: boolean;
+    mfaExemptRoles?: string[];
+    mfaRequiredRoles?: string[];
+    mfaTemplate?: {
+        templateId?: string;
+        templateName?: string;
+    };
+    requireMfaForAllUsers?: boolean;
+    userMfaType?: number[];
+};
 export type BlocksMfaGenerateRequest = {
     /** IAM-defined numeric MFA method (its enum names aren't in the swagger contract -- treat as opaque). */
     mfaType: number;

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

@@ -0,0 +1,43 @@
+import { BlocksHttpClient } from "../http/http-client.js";
+import { BlocksGetNotificationsOptions, BlocksGetNotificationsResponse, BlocksGetUnreadNotificationsBySubscriptionFilterRequest, BlocksMarkNotificationAsReadRequest, BlocksNotifierPassThroughResponse, BlocksNotifyRequest, BlocksOfflineNotification } from "./types.js";
+/**
+ * Real-time/offline notification surface: push a notification to specific users, roles, or
+ * subscription-filter matches, and read/manage the signed-in user's own notification inbox.
+ * Tenant-wide notification *channel configuration* (Notification/Save etc., under
+ * `BlocksIAMClient`/CLI `notification` commands) is a separate, admin-facing concern.
+ */
+export declare class BlocksNotifierClient {
+    private readonly http;
+    constructor(http: BlocksHttpClient);
+    /**
+     * What: pushes a notification through `POST /logic/v4/Notifier/Notify`.
+     * Why: app code needs to notify specific users/roles, or everyone subscribed to a filter, in real time with an offline/persisted fallback.
+     * How: target with at least one of `userIds`/`roles`/`subscriptionFilters`; set `saveDenormalizedPayloadAsAnObject` if `denormalizedPayload` is a JSON string clients should receive parsed.
+     */
+    notify(request: BlocksNotifyRequest): Promise<BlocksNotifierPassThroughResponse>;
+    /**
+     * What: reads unread notifications matching a subscription filter through `GET /logic/v4/Notifier/GetUnreadNotificationsBySubscriptionFilter`.
+     * Why: clients that subscribe by filter (rather than by user id) need to catch up on what they missed while offline.
+     * How: pass `userId` and the same `subscriptionFilterData` shape used with `notify`. Swagger documents this endpoint
+     * as GET with a JSON body, which the Fetch spec forbids -- the SDK sends the same fields as a flattened query string instead.
+     */
+    getUnreadNotificationsBySubscriptionFilter(request: BlocksGetUnreadNotificationsBySubscriptionFilterRequest): Promise<BlocksOfflineNotification[]>;
+    /**
+     * What: lists the signed-in user's notifications through `GET /logic/v4/Notifier/GetNotifications`.
+     * Why: notification-inbox UIs need paged, sortable, filterable access plus unread/total counts.
+     * How: pass paging/sort/filter options; omit them for the API's defaults.
+     */
+    getNotifications(options?: BlocksGetNotificationsOptions): Promise<BlocksGetNotificationsResponse>;
+    /**
+     * What: marks every notification read through `POST /logic/v4/Notifier/MarkAllNotificationAsRead`.
+     * Why: inbox UIs offer a bulk "mark all as read" action.
+     * How: call with an authorized token for the signed-in user.
+     */
+    markAllNotificationAsRead(): Promise<BlocksNotifierPassThroughResponse>;
+    /**
+     * What: marks one notification read through `POST /logic/v4/Notifier/MarkNotificationAsRead`.
+     * Why: inbox UIs mark individual notifications read as the user views them.
+     * How: pass the notification's `id`.
+     */
+    markNotificationAsRead(request: BlocksMarkNotificationAsReadRequest): Promise<BlocksNotifierPassThroughResponse>;
+}

package/dist/notifier/notifier-client.js

@@ -0,0 +1,71 @@
+const NOTIFIER_API = "/logic/v4/Notifier";
+/**
+ * Real-time/offline notification surface: push a notification to specific users, roles, or
+ * subscription-filter matches, and read/manage the signed-in user's own notification inbox.
+ * Tenant-wide notification *channel configuration* (Notification/Save etc., under
+ * `BlocksIAMClient`/CLI `notification` commands) is a separate, admin-facing concern.
+ */
+export class BlocksNotifierClient {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * What: pushes a notification through `POST /logic/v4/Notifier/Notify`.
+     * Why: app code needs to notify specific users/roles, or everyone subscribed to a filter, in real time with an offline/persisted fallback.
+     * How: target with at least one of `userIds`/`roles`/`subscriptionFilters`; set `saveDenormalizedPayloadAsAnObject` if `denormalizedPayload` is a JSON string clients should receive parsed.
+     */
+    notify(request) {
+        return this.http.request(`${NOTIFIER_API}/Notify`, { body: request });
+    }
+    /**
+     * What: reads unread notifications matching a subscription filter through `GET /logic/v4/Notifier/GetUnreadNotificationsBySubscriptionFilter`.
+     * Why: clients that subscribe by filter (rather than by user id) need to catch up on what they missed while offline.
+     * How: pass `userId` and the same `subscriptionFilterData` shape used with `notify`. Swagger documents this endpoint
+     * as GET with a JSON body, which the Fetch spec forbids -- the SDK sends the same fields as a flattened query string instead.
+     */
+    getUnreadNotificationsBySubscriptionFilter(request) {
+        return this.http.request(`${NOTIFIER_API}/GetUnreadNotificationsBySubscriptionFilter`, {
+            query: {
+                OrderBy: request.orderBy,
+                "SubscriptionFilterData.ActionName": request.subscriptionFilterData?.actionName,
+                "SubscriptionFilterData.Context": request.subscriptionFilterData?.context,
+                "SubscriptionFilterData.Value": request.subscriptionFilterData?.value,
+                UserId: request.userId
+            }
+        });
+    }
+    /**
+     * What: lists the signed-in user's notifications through `GET /logic/v4/Notifier/GetNotifications`.
+     * Why: notification-inbox UIs need paged, sortable, filterable access plus unread/total counts.
+     * How: pass paging/sort/filter options; omit them for the API's defaults.
+     */
+    getNotifications(options = {}) {
+        return this.http.request(`${NOTIFIER_API}/GetNotifications`, {
+            query: {
+                Filter: options.filter,
+                IsUnreadOnly: options.isUnreadOnly,
+                Page: options.page,
+                PageSize: options.pageSize,
+                "Sort.IsDescending": options.sortDescending,
+                "Sort.Property": options.sortBy
+            }
+        });
+    }
+    /**
+     * What: marks every notification read through `POST /logic/v4/Notifier/MarkAllNotificationAsRead`.
+     * Why: inbox UIs offer a bulk "mark all as read" action.
+     * How: call with an authorized token for the signed-in user.
+     */
+    markAllNotificationAsRead() {
+        return this.http.request(`${NOTIFIER_API}/MarkAllNotificationAsRead`, { method: "POST" });
+    }
+    /**
+     * What: marks one notification read through `POST /logic/v4/Notifier/MarkNotificationAsRead`.
+     * Why: inbox UIs mark individual notifications read as the user views them.
+     * How: pass the notification's `id`.
+     */
+    markNotificationAsRead(request) {
+        return this.http.request(`${NOTIFIER_API}/MarkNotificationAsRead`, { body: request });
+    }
+}

package/dist/notifier/types.d.ts

@@ -0,0 +1,50 @@
+export type BlocksNotifierSubscriptionFilter = {
+    actionName?: string;
+    context?: string;
+    value?: string;
+};
+export type BlocksNotifyRequest = {
+    configurationName?: string;
+    connectionId?: string;
+    contentAvailable?: boolean;
+    denormalizedPayload?: string;
+    responseKey?: string;
+    responseValue?: string;
+    roles?: string[];
+    saveDenormalizedPayloadAsAnObject?: boolean;
+    subscriptionFilters?: BlocksNotifierSubscriptionFilter[];
+    userIds?: string[];
+};
+export type BlocksGetUnreadNotificationsBySubscriptionFilterRequest = {
+    /** IAM/Notifier-defined order enum (its meanings aren't in the swagger contract -- treat as opaque). */
+    orderBy?: 1 | 2;
+    subscriptionFilterData?: BlocksNotifierSubscriptionFilter;
+    userId?: string;
+};
+export type BlocksGetNotificationsOptions = {
+    filter?: string;
+    isUnreadOnly?: boolean;
+    page?: number;
+    pageSize?: number;
+    sortBy?: string;
+    sortDescending?: boolean;
+};
+export type BlocksOfflineNotification = Record<string, unknown> & {
+    correlationId?: string;
+    createdTime?: string;
+    denormalizedPayload?: string;
+    id?: string;
+    isRead?: boolean;
+    payload?: string;
+    readByRoles?: string[];
+    readByUserIds?: string[];
+};
+export type BlocksGetNotificationsResponse = {
+    notifications: Record<string, unknown>[];
+    totalNotificationsCount: number;
+    unReadNotificationsCount: number;
+};
+export type BlocksMarkNotificationAsReadRequest = {
+    id: string;
+};
+export type BlocksNotifierPassThroughResponse = Record<string, unknown>;

package/dist/notifier/types.js

@@ -0,0 +1 @@
+export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@seliseblocks/client",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Framework-neutral TypeScript client SDK for SELISE Blocks frontend applications.",
   "license": "MIT",
   "type": "module",