qati-sdk 1.0.4 → 1.0.5

package/README.md

@@ -13,6 +13,8 @@ The main feature groups on the client are:
 - `client.advisory` — list persisted advisories for the tenant (with filters and pagination).
 - `client.explain` — fetch a composite explain / attribution payload for a single entity (by entity key).
 - `client.events` — send telemetry events to the ingestion pipeline.
+- `client.webhooks` — manage webhook endpoints for a tenant (register, list, update, delete, trigger test delivery).
+- `client.quotas` — read and configure numeric caps (entities, monthly events, rate) for a tenant.
 
 No network traffic occurs until you call a method. Opening a client only prepares HTTP connections and resolves configuration.
 
@@ -166,6 +168,138 @@ try {
 }
 ```
 
+## Webhooks
+
+`client.webhooks` manages webhook endpoints for a specific tenant. All methods require `tenantId` as their first argument — resolve it once with `client.tenant.verifyCredentials()` and reuse the value.
+
+Supported event types: `trust_state.tier_escalated`, `advisory.created`.
+
+### Register a webhook
+
+```ts
+import { Session } from 'qati-sdk';
+
+const session = new Session();
+const client = session.createClient();
+try {
+  const creds = await client.tenant.verifyCredentials();
+  const webhook = await client.webhooks.create(creds.tenant_id, {
+    url: 'https://your-service.example.com/qati-events',
+    subscribed_event_types: ['trust_state.tier_escalated', 'advisory.created'],
+    enabled: true,
+  });
+  // webhook.secret is returned exactly once — store it for HMAC verification.
+  console.log(webhook.id, webhook.secret);
+} finally {
+  await client.close();
+}
+```
+
+The `secret` field in the response is shown **only on creation**. Store it securely; you cannot retrieve it again. To rotate the secret, use `patch` with `rotate_secret: true`.
+
+### List webhooks
+
+```ts
+const hooks = await client.webhooks.list(tenantId);
+for (const h of hooks) {
+  console.log(h.id, h.url, h.enabled, h.consecutive_failures);
+}
+```
+
+### Update a webhook
+
+Any field is optional. Pass `rotate_secret: true` to get a new signing secret (returned in `new_secret`).
+
+```ts
+const updated = await client.webhooks.patch(tenantId, webhookId, {
+  enabled: false,
+  subscribed_event_types: ['advisory.created'],
+});
+```
+
+### Trigger a test delivery
+
+Enqueues a synthetic event to the webhook. Useful for verifying your receiver end-to-end.
+
+```ts
+const { delivery_id } = await client.webhooks.test(tenantId, webhookId);
+console.log('test delivery queued:', delivery_id);
+```
+
+### Delete a webhook
+
+```ts
+await client.webhooks.delete(tenantId, webhookId);
+```
+
+### Verifying signatures
+
+The platform signs every delivery with HMAC-SHA256. The signature is in the `X-QATI-Signature` header as `v1=<hex>`. The signed message is `"<unix_timestamp>.<raw_utf8_body>"` where the timestamp comes from `X-QATI-Timestamp`.
+
+```ts
+import crypto from 'crypto';
+
+function verifySignature(
+  rawBody: string,
+  timestamp: string,
+  signature: string,
+  secret: string,
+): boolean {
+  const expected =
+    'v1=' +
+    crypto
+      .createHmac('sha256', secret)
+      .update(`${timestamp}.${rawBody}`, 'utf8')
+      .digest('hex');
+  if (signature.length !== expected.length) return false;
+  return crypto.timingSafeEqual(
+    Buffer.from(signature, 'utf8'),
+    Buffer.from(expected, 'utf8'),
+  );
+}
+```
+
+Use `express.text({ type: 'application/json' })` (not `express.json()`) to capture the raw body string before parsing, so the HMAC is computed over the exact bytes the platform signed.
+
+---
+
+## Quotas
+
+`client.quotas` reads and writes the numeric caps that govern how much a tenant can send and store.
+
+### Get current quotas
+
+Returns the active limits; throws `QatiNotFoundError` (404) if no quota has been configured for the tenant yet.
+
+```ts
+import { Session } from 'qati-sdk';
+
+const session = new Session();
+const client = session.createClient();
+try {
+  const creds = await client.tenant.verifyCredentials();
+  const quota = await client.quotas.get(creds.tenant_id);
+  console.log(quota.max_tracked_entities, quota.max_monthly_events, quota.max_events_per_second);
+} finally {
+  await client.close();
+}
+```
+
+### Upsert quotas
+
+Creates or fully replaces the quota configuration. All three fields are required.
+
+```ts
+const quota = await client.quotas.upsert(tenantId, {
+  max_tracked_entities: 50000,
+  max_monthly_events: 5_000_000,
+  max_events_per_second: 1000,
+});
+console.log(quota.id, quota.tenant_id);
+```
+
+---
+
 ## Step 3 Configure the session
 
 For most teams, environment variables are the simplest approach — set them once and the SDK picks them up automatically (via `dotenv` loading `.env` from the working directory when using `new Session()` / `resolveQatiConfig()`). If you need finer control (custom URLs, timeouts, or multiple tenants), pass a config object into `Session`.
@@ -540,13 +674,15 @@ Transient failures are retried automatically for **`POST /v1/events:batch`** acc
 
 ## Appendix: API surface (compact)
 
-| Symbol          | Role                                                                                                                                                                                                       |
-| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `Session`       | `new Session(config?)`, `session.config`, `session.createClient(httpClients?)`.                                                                                                                            |
-| `Client`        | Namespaces: `tenant`, `trustState`, `advisory`, `explain`, `events`; `await client.close()`.                                                                                                               |
-| `client.events` | `enqueue`, `flush`, `shutdown`, `pendingCount`, `onIngestionFailure`.                                                                                                                                      |
-| `create*Event`  | `createTransactionEvent`, `createAuthEvent`, `createModelOutputEvent`, `createSystemTelemetryEvent`, `createAnomalyFlagEvent`, `createBehaviorEvent`, `createNetworkEvent` — all exported from `qati-sdk`. |
-| Config          | `resolveQatiConfig`, `parseQatiConfig`, `baseUrlFor`, types `QatiConfigInput` / `QatiConfigOutput`.                                                                                                        |
-| Errors          | `QatiSDKError`, `QatiAPIError`, `QatiAuthError`, `QatiNotFoundError`, `QatiRateLimitError`, `QatiServerError`, `QatiConfigError`.                                                                          |
+| Symbol             | Role                                                                                                                                                                                                       |
+| ------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `Session`          | `new Session(config?)`, `session.config`, `session.createClient(httpClients?)`.                                                                                                                            |
+| `Client`           | Namespaces: `tenant`, `trustState`, `advisory`, `explain`, `events`, `webhooks`, `quotas`; `await client.close()`.                                                                                         |
+| `client.events`    | `enqueue`, `flush`, `shutdown`, `pendingCount`, `onIngestionFailure`.                                                                                                                                      |
+| `client.webhooks`  | `list(tenantId)`, `create(tenantId, body)`, `patch(tenantId, webhookId, body)`, `delete(tenantId, webhookId)`, `test(tenantId, webhookId)`.                                                                |
+| `client.quotas`    | `get(tenantId)`, `upsert(tenantId, body)`.                                                                                                                                                                 |
+| `create*Event`     | `createTransactionEvent`, `createAuthEvent`, `createModelOutputEvent`, `createSystemTelemetryEvent`, `createAnomalyFlagEvent`, `createBehaviorEvent`, `createNetworkEvent` — all exported from `qati-sdk`. |
+| Config             | `resolveQatiConfig`, `parseQatiConfig`, `baseUrlFor`, types `QatiConfigInput` / `QatiConfigOutput`.                                                                                                        |
+| Errors             | `QatiSDKError`, `QatiAPIError`, `QatiAuthError`, `QatiNotFoundError`, `QatiRateLimitError`, `QatiServerError`, `QatiConfigError`.                                                                          |
 
 `HttpClient.request(...)` exists for advanced use; prefer resource methods for application code.

package/dist/index.cjs

@@ -78,19 +78,6 @@ var QatiConfigError = class extends QatiSDKError {
 };
 
 // src/config.ts
-var EV_VARIABLES_NAMES = [
-  "QATI_TENANT_API_KEY",
-  "QATI_QUERY_API_BASE_URL",
-  "QATI_INGESTION_API_BASE_URL",
-  "QATI_TIMEOUT",
-  "QATI_MAX_RETRIES",
-  "QATI_INGESTION_BATCH_SIZE",
-  "QATI_INGESTION_FLUSH_INTERVAL_SECONDS",
-  "QATI_RETRY_BACKOFF_INITIAL_SECONDS",
-  "QATI_RETRY_BACKOFF_MAX_SECONDS",
-  "QATI_RETRY_JITTER_FRACTION",
-  "QATI_MAX_RETRIES"
-];
 var API_REGISTRY = {
   query_api: "queryApiBaseUrl",
   ingestion_api: "ingestionApiBaseUrl"
@@ -115,14 +102,22 @@ var stripUndefined = (obj) => {
 };
 var readEnvOverrides = () => {
   const e = process.env;
-  const sanitizedEnvs = EV_VARIABLES_NAMES.reduce(
-    (acc, ev) => {
-      acc[ev] = e[ev];
-      return acc;
-    },
-    {}
-  );
-  return sanitizedEnvs;
+  const num = (key) => {
+    const v = e[key];
+    return v !== void 0 ? Number(v) : void 0;
+  };
+  return {
+    tenantApiKey: e["QATI_TENANT_API_KEY"],
+    queryApiBaseUrl: e["QATI_QUERY_API_BASE_URL"],
+    ingestionApiBaseUrl: e["QATI_INGESTION_API_BASE_URL"],
+    timeout: num("QATI_TIMEOUT"),
+    maxRetries: num("QATI_MAX_RETRIES"),
+    ingestionBatchSize: num("QATI_INGESTION_BATCH_SIZE"),
+    ingestionFlushIntervalSeconds: num("QATI_INGESTION_FLUSH_INTERVAL_SECONDS"),
+    retryBackoffInitialSeconds: num("QATI_RETRY_BACKOFF_INITIAL_SECONDS"),
+    retryBackoffMaxSeconds: num("QATI_RETRY_BACKOFF_MAX_SECONDS"),
+    retryJitterFraction: num("QATI_RETRY_JITTER_FRACTION")
+  };
 };
 var resolveQatiConfig = (input) => {
   dotenv.config({ path: ".env" });
@@ -607,6 +602,29 @@ var ExplainResource = class {
   }
 };
 
+// src/resources/quota-resource.ts
+var QuotaResource = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  _http;
+  apiName = "query_api";
+  async get(tenantId) {
+    return this._http.request(
+      "GET",
+      `/v1/tenants/${encodeURIComponent(tenantId)}/quotas`,
+      { api_name: this.apiName }
+    );
+  }
+  async upsert(tenantId, body) {
+    return this._http.request(
+      "PUT",
+      `/v1/tenants/${encodeURIComponent(tenantId)}/quotas`,
+      { api_name: this.apiName, data: body }
+    );
+  }
+};
+
 // src/resources/tenant-resource.ts
 var TenantResource = class {
   constructor(_http) {
@@ -680,6 +698,50 @@ var TrustStateResource = class {
   }
 };
 
+// src/resources/webhook-resource.ts
+var WebhookResource = class {
+  constructor(_http) {
+    this._http = _http;
+  }
+  _http;
+  apiName = "query_api";
+  async list(tenantId) {
+    return this._http.request(
+      "GET",
+      `/v1/tenants/${encodeURIComponent(tenantId)}/webhooks`,
+      { api_name: this.apiName }
+    );
+  }
+  async create(tenantId, body) {
+    return this._http.request(
+      "POST",
+      `/v1/tenants/${encodeURIComponent(tenantId)}/webhooks`,
+      { api_name: this.apiName, data: body }
+    );
+  }
+  async patch(tenantId, webhookId, body) {
+    return this._http.request(
+      "PATCH",
+      `/v1/tenants/${encodeURIComponent(tenantId)}/webhooks/${encodeURIComponent(webhookId)}`,
+      { api_name: this.apiName, data: body }
+    );
+  }
+  async delete(tenantId, webhookId) {
+    const instance = this._http.getClient(this.apiName);
+    await instance.request({
+      method: "DELETE",
+      url: `/v1/tenants/${encodeURIComponent(tenantId)}/webhooks/${encodeURIComponent(webhookId)}`
+    });
+  }
+  async test(tenantId, webhookId) {
+    return this._http.request(
+      "POST",
+      `/v1/tenants/${encodeURIComponent(tenantId)}/webhooks/${encodeURIComponent(webhookId)}/test`,
+      { api_name: this.apiName }
+    );
+  }
+};
+
 // src/client/client.ts
 var Client = class extends HttpClient {
   _tenant;
@@ -687,6 +749,8 @@ var Client = class extends HttpClient {
   _advisory;
   _explain;
   _events;
+  _webhooks;
+  _quotas;
   /**
    * @param config - Resolved SDK configuration (typically `session.config`).
    * @param axiosInstances - Optional per-API `axios` instances; see {@link Session#createClient}.
@@ -699,6 +763,8 @@ var Client = class extends HttpClient {
     this._advisory = new AdvisoryResource(this);
     this._explain = new ExplainResource(this);
     this._events = new EventResource(this);
+    this._webhooks = new WebhookResource(this);
+    this._quotas = new QuotaResource(this);
   }
   /**
    * Tenant API surface (credentials verification).
@@ -740,6 +806,24 @@ var Client = class extends HttpClient {
   get events() {
     return this._events;
   }
+  /**
+   * Webhook endpoint management for a tenant (create, list, patch, delete, test delivery).
+   *
+   * All methods require `tenantId` explicitly; resolve it once via `client.tenant.verifyCredentials()`.
+   *
+   * @returns {@link WebhookResource} for the Query API.
+   */
+  get webhooks() {
+    return this._webhooks;
+  }
+  /**
+   * Tenant quota configuration (get and upsert numeric caps).
+   *
+   * @returns {@link QuotaResource} for the Query API.
+   */
+  get quotas() {
+    return this._quotas;
+  }
   /**
    * Flushes the event ingestion buffer (best-effort), then shuts down the batch scheduler.
    * Call this on process shutdown so queued events are not lost.