@seliseblocks/client 0.2.0 → 0.3.0

package/AGENT_GUIDE.md

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

package/CHANGELOG.md

@@ -6,6 +6,91 @@ 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.3.0
+
+### Added
+
+- `blocks.logic` -- the blocks-logic runtime surface:
+  - `logic.functions.call(id, options)` invokes a deployed function and returns
+    its value whether it is deployed sync (the answer's body) or async (polls the
+    run, parses its result). A returned `{ statusCode, headers, body }` is
+    unwrapped to `body` so both modes read alike. A run that fails or times out
+    throws the new `BlocksFunctionRunError`.
+  - `logic.functions.invoke()` returns the transport result --
+    `{ kind: "answered", status, headers, body, runId? }` or
+    `{ kind: "accepted", runId, runStatus, pollToken }` -- with `respondAsync` /
+    `waitSeconds` mapped to the `Prefer` header; `waitForResult()`,
+    `getResult(runId, pollToken)` and `getRun(runId)` collect a queued run;
+    `invokeRaw()` returns the unread `Response` for streaming handlers;
+    `url()` gives the public address.
+  - `logic.proxy.request(slug, options)` / `requestRaw()` / `url()` call a
+    configured proxy's gateway route.
+- `@seliseblocks/client/functions` -- type-only declarations of the function
+  sandbox contract (`FunctionHandler`, `FunctionInput`, `FunctionContext`,
+  `FunctionHttpResponse`, …) for editor checking of a function's `index.js`.
+  Nothing from it is needed at runtime inside a function.
+- `http.send(path, options)` -- the same authenticated request as
+  `http.request`, returning the unread `Response` (status and headers intact,
+  never throws on a non-2xx). `request` is now built on it, unchanged.
+- Request `query` values may be arrays (a repeated key), and requests take an
+  `AbortSignal` (`signal`).
+
+### Fixed
+
+- `auth.switchOrganization({ organizationId })` now sends IAM's
+  `organization_id`.
+  - Why: IAM binds `SwitchOrganizationRequest.OrganizationId` only as
+    `organization_id` (`[JsonPropertyName]`). The SDK sent the camelCase name,
+    so every call that followed the documented type failed with 400
+    `organization_id is required`.
+  - Compatible: the type is unchanged. A caller already sending
+    `organization_id` keeps working, and that value still wins when both are
+    given, matching what IAM bound before. Other extra fields pass through as
+    before.
+  - `refreshToken` on this request is deprecated and no longer sent. IAM's
+    switch-org reads the refresh token only from the session cookie (or its
+    `rt_<domain>` header), never from the body. It had no effect, and sending
+    it only put a secret in a request body. Switch organization from a browser
+    session that holds the IAM cookie.
+- `BlocksApiError.message` now includes the reason from validation responses.
+  - Why: the message was built only from `message`, `detail`,
+    `error_description` and `error`. ASP.NET validation responses
+    (`{ title, errors }`) and Blocks mutation responses (`{ errors: { Field:
+    "text" } }`) carry the reason in `errors`, so the message was only the
+    status line (`Blocks API 400 Bad Request`) and the reason sat unseen in
+    `.body`.
+  - What: when none of those four fields is present, the message adds the
+    `errors` entries (`Field: text`, first five fields), or else `title`.
+  - Compatible: `status`, `statusText` and `body` are unchanged, and a body
+    that already had `message` / `detail` / `error_description` / `error`
+    gives exactly the same message as before.
+
+### Fixed (blocks-site reports)
+
+- `notifier.notify` fills `connectionId`, `responseKey` and `responseValue` with
+  `server` / `notification` / `notification` when omitted. The service binds all
+  three as required strings, so the documented minimal call failed with 400
+  (95737817). `organizationIds` is added to the request type. A send needs a
+  user whose role has `blocks-logic::notifier::send`; blocks-logic answers 401
+  otherwise.
+- `iam.users.emailAvailable` and `iam.users.exists` use IAM's POST forms; the
+  deprecated GETs put the address in the URL (3b86fd8d). `emailAvailable` now
+  sends the signed-in user's token: IAM protects it with
+  `blocks-iam::iam::email-available`, so it no longer works before sign-in.
+
+### Breaking (type-level)
+
+- `iam.users.activate` takes `BlocksActivateUserRequest` (`{ userId, reason }`,
+  both required) instead of `Record<string, unknown>`. IAM requires `reason`, so a
+  call without it always failed with 400; the type now says so (bacbaebd).
+- `BlocksNotifyRequest.configurationName` and `.denormalizedPayload` are required.
+  Every send without them was already refused by the service (95737817).
+
+### Changed
+
+- `iam.organizations.list` accepts an array for `Filter.Ids`; its JSDoc documents
+  that IAM pages from 0 and refuses `Filter.*` without a non-empty `Filter.Search`.
+
 ## 0.2.0
 
 ### Breaking