feat(logs): write app log lines, getLog, Retry-After on NorbixError

README.md

@@ -351,6 +351,7 @@ Default base URL: `https://api.norbix.ai`. **8 modules · 66 endpoints.**
 | 🔑 `apikeys`     | List + regenerate per-environment API keys                                                    | [`docs/api/apikeys.md`](./docs/api/apikeys.md)           |
 | 🪪 `accessToken` | Refresh-token exchange                                                                        | [`docs/api/access_token.md`](./docs/api/access_token.md) |
 | 🩺 `echo`        | Gateway smoke check                                                                           | [`docs/api/echo.md`](./docs/api/echo.md)                 |
+| 📊 `logs`        | Write your app's own log lines (`write` / `writeLogs`) to the project's Logs                  | [`docs/api/logs.md`](./docs/api/logs.md)                 |
 
 > Email/push/SMS notifications, payments, and code execution are configured on the **Hub** surface and surfaced at runtime through integration triggers — they are not separate API modules. File storage now has its own `files` API module: it issues signed upload URLs so clients upload binary content directly to storage, never streaming bytes through the Norbix API.
 
@@ -372,7 +373,7 @@ Default base URL: `https://hub.norbix.ai`. **18 modules · 315 endpoints.**
 | 📨 `email`                | Email module switches                                                   | [`docs/hub/email.md`](./docs/hub/email.md)                 |
 | 💳 `payments`             | Payment integrations, triggers, tests, module settings                  | [`docs/hub/payments.md`](./docs/hub/payments.md)           |
 | 🤖 `ai`                   | LLM and MCP integration configuration and tests                         | [`docs/hub/ai.md`](./docs/hub/ai.md)                       |
-| 📊 `logs`                 | Logging integrations and module settings                                | [`docs/hub/logs.md`](./docs/hub/logs.md)                   |
+| 📊 `logs`                 | Read logs (list, one entry, trail), settings, integrations and tests    | [`docs/hub/logs.md`](./docs/hub/logs.md)                   |
 | 👥 `membership`           | Roles, policies, users, preferences, integrations, triggers             | [`docs/hub/membership.md`](./docs/hub/membership.md)       |
 | ⏰ `scheduler`            | Scheduler module, tasks and their run history                           | [`docs/hub/scheduler.md`](./docs/hub/scheduler.md)         |
 | 🪝 `webhooks`             | Webhook integrations, destinations, tests, module settings              | [`docs/hub/webhooks.md`](./docs/hub/webhooks.md)           |
@@ -758,6 +759,11 @@ try {
 }
 ```
 
+When the answer carries a `Retry-After` header (a 429 from
+`norbix.api.logs.write` when the project's per-minute log quota is used up),
+`err.retryAfterSeconds` holds it in seconds. The SDK retries a 429 by itself
+only for GET and DELETE; anything else is yours to send again.
+
 `message` and `errorCode` are the gateway's own. The gateway puts them inside
 `responseStatus.errors[]`, so a `NorbixError` reads that list first, takes the
 first entry for `message` / `errorCode`, and keeps every entry in `errors`.

docs/README.md

@@ -8,8 +8,8 @@ integration guides live under `integrations/`.
 
 | Surface                  |                    Modules | Description                                                                                      |
 | ------------------------ | -------------------------: | ------------------------------------------------------------------------------------------------ |
-| [`API`](./api/_index.md) | 11 modules · 120 endpoints | Project-scoped data operations: database collections, users, AI chat, auth, API keys.            |
-| [`Hub`](./hub/_index.md) | 27 modules · 582 endpoints | Project & account configuration: schemas, integrations, team management, billing, observability. |
+| [`API`](./api/_index.md) | 12 modules · 122 endpoints | Project-scoped data operations: database collections, users, AI chat, auth, API keys.            |
+| [`Hub`](./hub/_index.md) | 27 modules · 590 endpoints | Project & account configuration: schemas, integrations, team management, billing, observability. |
 
 ## Integration guides
 

docs/api/_index.md

@@ -4,7 +4,7 @@
 
 Project-scoped data operations: database collections, users, AI chat, auth, API keys.
 
-**120 endpoints across 11 modules.** Click a module
+**122 endpoints across 12 modules.** Click a module
 name for the full method reference and TypeScript examples.
 
 | Module                                | Endpoints | Description                                                                                                                              |
@@ -15,7 +15,8 @@ name for the full method reference and TypeScript examples.
 | [`auth`](./auth.md)                   |         1 | Sign-in / sign-out and federated provider flows. Most apps prefer `norbix.login(...)` over calling these directly.                       |
 | [`database`](./database.md)           |        22 | Database schemas, integrations, triggers, taxonomies, and module on/off switches. For data-level CRUD on collections see `api.database`. |
 | [`echo`](./echo.md)                   |         1 | Echo helpers used by the gateway smoke checks.                                                                                           |
-| [`files`](./files.md)                 |        14 | File storage integrations and triggers. Upload + download is in `api.database` (FileResource fields).                                    |
+| [`files`](./files.md)                 |        15 | File storage integrations and triggers. Upload + download is in `api.database` (FileResource fields).                                    |
+| [`logs`](./logs.md)                   |         1 | Logging integrations and module on/off switches.                                                                                         |
 | [`membership`](./membership.md)       |        43 | Roles, policies, and user preferences (Hub side). For user CRUD and registration see `api.membership`.                                   |
 | [`notifications`](./notifications.md) |        11 | Email and push templates, integrations, campaigns, devices, signatures, footers, and one-click unsubscribe.                              |
 | [`payments`](./payments.md)           |         4 | Payment provider integrations and triggers (Stripe, etc.).                                                                               |

docs/api/files.md

@@ -21,6 +21,7 @@ Accessed as `norbix.api.files` on the [`Norbix`](../../README.md#authentication)
 | [`getSignedUrl`](#getsignedurl)                 | `GET`    | `/{version}/files/{filesIntegrationId}/sign`       | `project` |
 | [`listFiles`](#listfiles)                       | `GET`    | `/{version}/files/{filesIntegrationId}`            | `project` |
 | [`getPublicFile`](#getpublicfile)               | `GET`    | `/{version}/files/public/{PublicId}/{Name*}`       | `project` |
+| [`registerFiles`](#registerfiles)               | `POST`   | `/{version}/files/{filesIntegrationId}/register`   | `project` |
 | [`requestUploadUrl`](#requestuploadurl)         | `POST`   | `/{version}/files/{filesIntegrationId}/upload-url` | `project` |
 | [`testFilesIntegration`](#testfilesintegration) | `POST`   | `/{version}/files/{filesIntegrationId}/test`       | `project` |
 | [`useFile`](#usefile)                           | `POST`   | `/{version}/files/{filesIntegrationId}/use`        | `project` |
@@ -274,6 +275,29 @@ const result = await norbix.api.files.getPublicFile({
 
 [↑ Top](#endpoints)
 
+### registerFiles
+
+`POST` `/{version}/files/{filesIntegrationId}/register`
+
+Register a new entry.
+
+**Request DTO**: `CodeMashApi2.RegisterFilesRequest`
+**Response**: `CodeMashApi2.RegisterFilesResponse`
+
+```ts
+import { Norbix } from '@norbix.ai/ts';
+
+const norbix = new Norbix();
+
+const result = await norbix.api.files.registerFiles({
+  filesIntegrationId: 'filesIntegrationId-here',
+  // Other fields: see CodeMash type for the full request shape.
+});
+// → typed as CodeMashApi2.RegisterFilesResponse
+```
+
+[↑ Top](#endpoints)
+
 ### requestUploadUrl
 
 `POST` `/{version}/files/{filesIntegrationId}/upload-url`

docs/api/logs.md

@@ -0,0 +1,90 @@
+# API · Logs
+
+[← Back to API index](./_index.md) · [↑ Back to project README](../../README.md)
+
+Logging integrations and module on/off switches.
+
+Accessed as `norbix.api.logs` on the [`Norbix`](../../README.md#authentication) client.
+
+## Endpoints
+
+| Method                    | Verb   | Path              | Scope     |
+| ------------------------- | ------ | ----------------- | --------- |
+| [`writeLogs`](#writelogs) | `POST` | `/{version}/logs` | `project` |
+
+## Reference
+
+### writeLogs
+
+`POST` `/{version}/logs`
+
+**Request DTO**: `CodeMashApi2.WriteLogs`
+**Response**: `CodeMashApi2.WriteLogsResponse`
+
+```ts
+import { Norbix } from '@norbix.ai/ts';
+
+const norbix = new Norbix();
+
+const result = await norbix.api.logs.writeLogs({
+  // See CodeMash type for the full request shape.
+});
+// → typed as CodeMashApi2.WriteLogsResponse
+```
+
+[↑ Top](#endpoints)
+
+<!-- @hand-written:begin -->
+
+## Writing your app's own log lines
+
+`norbix.api.logs` is not about integrations (those are on the Hub, see
+[`docs/hub/logs.md`](../hub/logs.md)): it sends **your app's own lines** to the
+project's Logs, where they show next to the lines Norbix writes.
+
+```ts
+import { Norbix, NorbixError } from '@norbix.ai/ts';
+
+const norbix = new Norbix();
+
+// One line …
+await norbix.api.logs.write({ title: 'Order paid', eventCode: 'order:paid' });
+
+// … or up to 100 at once. `writeLogs({ entries })` is the same call.
+const { accepted } = await norbix.api.logs.write([
+  {
+    level: 'warning', // information (default) | warning | error
+    title: 'Payment retried', // required, at most 200 characters
+    message: 'Card declined once, second try passed', // at most 8 000
+    eventCode: 'order:retry', // a-z 0-9 _ . : -, at most 64 — stored as app:order:retry
+    correlationId: 'ord_123', // letters, digits, _ or -, at most 64 — groups lines into one flow
+    timestamp: '2026-10-21T10:00:00Z', // UTC, at most 7 days old, at most 5 minutes ahead
+    meta: { orderId: 'ord_123' }, // at most 20 keys; secret-looking keys are masked
+  },
+]);
+```
+
+The answer comes at once: `accepted` lines are queued, not yet stored.
+
+| Refusal                       | When                                       |
+| ----------------------------- | ------------------------------------------ |
+| 400 (`NorbixValidationError`) | A line breaks one of the rules above.      |
+| 400 `CM-ERRORS-LOGGING-002`   | The Logs module is off for the project.    |
+| 429 `CM-ERRORS-LOGGING-003`   | The project's per-minute quota is used up. |
+
+On a 429 the SDK does not send again by itself (a POST is never retried).
+`err.retryAfterSeconds` holds the gateway's `Retry-After` value:
+
+```ts
+try {
+  await norbix.api.logs.write(lines);
+} catch (err) {
+  if (err instanceof NorbixError && err.httpStatus === 429) {
+    setTimeout(() => norbix.api.logs.write(lines), (err.retryAfterSeconds ?? 60) * 1000);
+  } else throw err;
+}
+```
+
+Tests: `tests/api/logs.test.ts`.
+
+<!-- @hand-written:end -->

docs/hub/_index.md

@@ -4,26 +4,26 @@
 
 Project & account configuration: schemas, integrations, team management, billing, observability.
 
-**582 endpoints across 27 modules.** Click a module
+**590 endpoints across 27 modules.** Click a module
 name for the full method reference and TypeScript examples.
 
 | Module                                | Endpoints | Description                                                                                                                              |
 | ------------------------------------- | --------: | ---------------------------------------------------------------------------------------------------------------------------------------- |
 | [`accessToken`](./access_token.md)    |         1 | Refresh-token exchange to get a new bearer token.                                                                                        |
-| [`account`](./account.md)             |       122 | Account profile, status, verification, team invites, and Stripe billing portal. Most write endpoints require `accountId` on the client.  |
+| [`account`](./account.md)             |       128 | Account profile, status, verification, team invites, and Stripe billing portal. Most write endpoints require `accountId` on the client.  |
 | [`ai`](./ai.md)                       |        26 |                                                                                                                                          |
 | [`apikeys`](./apikeys.md)             |         2 | List and regenerate per-environment API keys for service auth.                                                                           |
 | [`auth`](./auth.md)                   |         5 | Sign-in / sign-out and federated provider flows. Most apps prefer `norbix.login(...)` over calling these directly.                       |
 | [`code`](./code.md)                   |        44 |                                                                                                                                          |
 | [`compliance`](./compliance.md)       |        18 |                                                                                                                                          |
-| [`database`](./database.md)           |        74 | Database schemas, integrations, triggers, taxonomies, and module on/off switches. For data-level CRUD on collections see `api.database`. |
+| [`database`](./database.md)           |        75 | Database schemas, integrations, triggers, taxonomies, and module on/off switches. For data-level CRUD on collections see `api.database`. |
 | [`diagnostics`](./diagnostics.md)     |         7 |                                                                                                                                          |
 | [`echo`](./echo.md)                   |         1 | Echo helpers used by the gateway smoke checks.                                                                                           |
 | [`email`](./email.md)                 |         2 |                                                                                                                                          |
 | [`files`](./files.md)                 |        24 | File storage integrations and triggers. Upload + download is in `api.database` (FileResource fields).                                    |
 | [`internal`](./internal.md)           |         1 |                                                                                                                                          |
 | [`licensing`](./licensing.md)         |         3 |                                                                                                                                          |
-| [`logs`](./logs.md)                   |        14 | Logging integrations and module on/off switches.                                                                                         |
+| [`logs`](./logs.md)                   |        15 | Logging integrations and module on/off switches.                                                                                         |
 | [`membership`](./membership.md)       |        48 | Roles, policies, and user preferences (Hub side). For user CRUD and registration see `api.membership`.                                   |
 | [`notifications`](./notifications.md) |       128 | Email and push templates, integrations, campaigns, devices, signatures, footers, and one-click unsubscribe.                              |
 | [`oauth`](./oauth.md)                 |         6 |                                                                                                                                          |