@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/notifications.d.ts

@@ -0,0 +1,94 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.notifications` (Notifications): 2 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"delete_notifications_by_entity_notifications_by_entity_delete">;
+ *
+ * Reference with examples: notifications.md
+ */
+/* eslint-disable */
+
+/** `g8.api.notifications.<member>` -> the operationId it calls. */
+export interface NotificationsMembers {
+  deleteNotificationsByEntity: "delete_notifications_by_entity_notifications_by_entity_delete";
+  markNotificationsByEntityRead: "mark_notifications_by_entity_read_notifications_by_entity_read_put";
+}
+
+/** Input and output of every `g8.api.notifications` operation, keyed by operationId. */
+export interface NotificationsOperations {
+  /**
+   * DELETE /notifications/by-entity
+   * Delete Notifications By Entity
+   * tier: destructive · scope: inbox:delete
+   */
+  delete_notifications_by_entity_notifications_by_entity_delete: {
+    input: {
+    query: {
+      /** Record type the notification is about, e.g. `chat`. */
+      entity_type: string;
+      /** Id of that record. */
+      entity_id: string;
+      /** Narrow to one notification type. Pass the type you own - omitting it also deletes unrelated notifications on the same record. */
+      notification_type?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+  /**
+   * PUT /notifications/by-entity/read
+   * Mark Notifications By Entity Read
+   * tier: write · scope: inbox:write
+   */
+  mark_notifications_by_entity_read_notifications_by_entity_read_put: {
+    input: {
+    query: {
+      /** Record type the notification is about, e.g. `chat`. */
+      entity_type: string;
+      /** Id of that record. */
+      entity_id: string;
+      /** Narrow to one notification type. Pass the type you own - omitting it also marks unrelated notifications on the same record, such as a colleague's mention. */
+      notification_type?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_CrmRecordPayload_;
+  };
+}
+
+// 3 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_CrmRecordPayload_ {
+  data: CrmRecordPayload;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * An open envelope for one record, one dashboard or one job receipt.
+ *
+ * Open because most of these reads are COMPUTED shapes - an engagement
+ * summary, a next-best-step, an intelligence status - that grow with the
+ * product, and dropping a field from an advisory read makes it say "nothing
+ * to report" rather than "we did not tell you".
+ */
+export type CrmRecordPayload = Record<string, unknown>;
+
+export interface PaginationMeta {
+  /** Whether there are more pages */
+  has_next: boolean;
+  /** Items per page */
+  limit: number;
+  /** Opaque cursor for the next page; null when there are no more items. Pass it back as the `cursor` query param to fetch the following page without computing page numbers. */
+  next_cursor?: string | null;
+  /** Current page number (1-indexed) */
+  page: number;
+  /** Total number of items */
+  total: number;
+}

package/docs/api/notifications.md

@@ -0,0 +1,105 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.notifications`: Notifications
+
+2 operations (1 write, 1 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.notifications.*` as shown below, or by operationId with `g8.api.call(operationId, input)`.
+
+Every example below assumes this setup (server-side, API key):
+
+```ts
+import { g8 } from "@graph8/sdk";
+
+g8.init({ apiKey: process.env.G8_API_KEY! });
+```
+
+Example values are placeholders that match each field's type. Only required fields are shown. Every example is type-checked against the SDK in CI.
+
+Exact TypeScript types for every operation on this page, and every schema they use: [notifications.d.ts](notifications.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`deleteNotificationsByEntity`](#op-deletenotificationsbyentity) | `DELETE /api/v1/notifications/by-entity` | destructive | `inbox:delete` | Delete Notifications By Entity |
+| [`markNotificationsByEntityRead`](#op-marknotificationsbyentityread) | `PUT /api/v1/notifications/by-entity/read` | write | `inbox:write` | Mark Notifications By Entity Read |
+
+---
+
+<a id="op-deletenotificationsbyentity"></a>
+
+### `g8.api.notifications.deleteNotificationsByEntity(input)`
+
+**Delete Notifications By Entity**
+
+- HTTP: `DELETE /api/v1/notifications/by-entity`
+- operationId: `delete_notifications_by_entity_notifications_by_entity_delete` (also callable as `g8.api.call("delete_notifications_by_entity_notifications_by_entity_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `inbox:delete`
+
+Delete the whole team's notifications for one record.
+
+Removes the rows for every user in your organisation, not just the
+caller's. There is no undo, and unlike the read marker above nothing
+survives to show the notification existed - prefer
+`PUT /notifications/by-entity/read` unless the notification was noise.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.entity_type` | `string` | yes | Record type the notification is about, e.g. `chat`. |
+| `query.entity_id` | `string` | yes | Id of that record. |
+| `query.notification_type` | `string \| null` | no | Narrow to one notification type. Pass the type you own - omitting it also deletes unrelated notifications on the same record. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.notifications.deleteNotificationsByEntity({ query: { entity_type: "example", entity_id: "id" } });
+```
+
+---
+
+<a id="op-marknotificationsbyentityread"></a>
+
+### `g8.api.notifications.markNotificationsByEntityRead(input)`
+
+**Mark Notifications By Entity Read**
+
+- HTTP: `PUT /api/v1/notifications/by-entity/read`
+- operationId: `mark_notifications_by_entity_read_notifications_by_entity_read_put` (also callable as `g8.api.call("mark_notifications_by_entity_read_notifications_by_entity_read_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `inbox:write`
+
+Mark the whole team's notifications for one record as READ.
+
+The rows survive, stamped with who read them, so the bell can still show
+that someone acknowledged it. Idempotent: only unread rows are touched.
+
+Omitting `notification_type` is the wide option - it marks every
+notification anyone in the org holds for that record, including mentions
+that were meant for a person.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.entity_type` | `string` | yes | Record type the notification is about, e.g. `chat`. |
+| `query.entity_id` | `string` | yes | Id of that record. |
+| `query.notification_type` | `string \| null` | no | Narrow to one notification type. Pass the type you own - omitting it also marks unrelated notifications on the same record, such as a colleague's mention. |
+
+**Returns** `ApiResponse_CrmRecordPayload_`: the envelope `{ data: CrmRecordPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.notifications.markNotificationsByEntityRead({ query: { entity_type: "example", entity_id: "id" } });
+```