@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/eSignature.d.ts

@@ -0,0 +1,242 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.eSignature` (E-Signature): 7 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_envelope_envelopes_post">;
+ *
+ * Reference with examples: eSignature.md
+ */
+/* eslint-disable */
+
+/** `g8.api.eSignature.<member>` -> the operationId it calls. */
+export interface ESignatureMembers {
+  createEnvelope: "create_envelope_envelopes_post";
+  deleteEnvelope: "delete_envelope_envelopes__envelope_id__delete";
+  getEnvelope: "get_envelope_envelopes__envelope_id__get";
+  listEnvelopes: "list_envelopes_envelopes_get";
+  resendEnvelope: "resend_envelope_envelopes__envelope_id__resend_post";
+  sendEnvelope: "send_envelope_envelopes__envelope_id__send_post";
+  voidEnvelope: "void_envelope_envelopes__envelope_id__void_post";
+}
+
+/** Input and output of every `g8.api.eSignature` operation, keyed by operationId. */
+export interface ESignatureOperations {
+  /**
+   * POST /envelopes
+   * Create Envelope
+   * tier: write · scope: quotes:write
+   */
+  create_envelope_envelopes_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: CreateEnvelopeRequest;
+  };
+    output: ApiResponse_EnvelopePayload_;
+  };
+  /**
+   * DELETE /envelopes/{envelope_id}
+   * Delete Envelope
+   * tier: destructive · scope: quotes:delete
+   */
+  delete_envelope_envelopes__envelope_id__delete: {
+    input: {
+    path: {
+      /** Envelope id (UUID). */
+      envelope_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_EnvelopePayload_;
+  };
+  /**
+   * GET /envelopes/{envelope_id}
+   * Get Envelope
+   * tier: read · scope: quotes:read
+   */
+  get_envelope_envelopes__envelope_id__get: {
+    input: {
+    path: {
+      /** Envelope id (UUID). */
+      envelope_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_EnvelopePayload_;
+  };
+  /**
+   * GET /envelopes
+   * List Envelopes
+   * tier: read · scope: quotes:read
+   */
+  list_envelopes_envelopes_get: {
+    input: {
+    query?: {
+      /** `draft`, `sent`, `viewed`, `completed`, `voided`, `expired`. */
+      status?: string | null;
+      /** What produced the envelope, e.g. `quote`. */
+      source_type?: string | null;
+      /** The producing record's id. */
+      source_id?: string | null;
+      page?: number;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_EnvelopeListPayload_;
+  };
+  /**
+   * POST /envelopes/{envelope_id}/resend
+   * Resend Envelope
+   * tier: external · scope: quotes:run
+   */
+  resend_envelope_envelopes__envelope_id__resend_post: {
+    input: {
+    path: {
+      /** Envelope id (UUID). */
+      envelope_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_EnvelopePayload_;
+  };
+  /**
+   * POST /envelopes/{envelope_id}/send
+   * Send Envelope
+   * tier: external · scope: quotes:run
+   */
+  send_envelope_envelopes__envelope_id__send_post: {
+    input: {
+    path: {
+      /** Envelope id (UUID). */
+      envelope_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: SendEnvelopeRequest;
+  };
+    output: ApiResponse_EnvelopePayload_;
+  };
+  /**
+   * POST /envelopes/{envelope_id}/void
+   * Void Envelope
+   * tier: destructive · scope: quotes:delete
+   */
+  void_envelope_envelopes__envelope_id__void_post: {
+    input: {
+    path: {
+      /** Envelope id (UUID). */
+      envelope_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_EnvelopePayload_;
+  };
+}
+
+// 8 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_EnvelopeListPayload_ {
+  data: EnvelopeListPayload;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_EnvelopePayload_ {
+  data: EnvelopePayload;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * Create a DRAFT envelope. Nothing is emailed until it is sent.
+ *
+ * Exactly one signer. The app's model carries one `signer_name` /
+ * `signer_email` pair rather than a list, so this does too - a mirror that
+ * invented a list would accept a second signer that is silently dropped.
+ */
+export interface CreateEnvelopeRequest {
+  /** At least one document - an empty envelope has nothing to sign. */
+  documents: Array<EnvelopeDocument>;
+  /** How long the signing link stays valid, counted from CREATION rather than from send. */
+  expires_in_days?: number;
+  /** Covering note in the signing email. */
+  message?: string | null;
+  /** Link the envelope to a graph8 contact record. */
+  signer_contact_id?: number | null;
+  signer_email: string;
+  signer_name: string;
+  /** The producing record's id. */
+  source_id?: string | null;
+  /** What produced this envelope, e.g. `quote`. Free-form, and filterable on list. */
+  source_type?: string | null;
+  /** Subject line the signer sees. */
+  subject: string;
+}
+
+/**
+ * One document inside an envelope.
+ *
+ * `content_html` IS the document - there is no upload step and no file. That
+ * is why this surface has no multipart endpoint: an envelope is created from
+ * HTML the caller already holds, which is what makes it scriptable.
+ */
+export interface EnvelopeDocument {
+  /** The document body as HTML. Rendered to the PDF the signer sees. */
+  content_html: string;
+  title: string;
+}
+
+/** A page of envelopes. */
+export interface EnvelopeListPayload {
+  items?: Array<unknown>;
+  limit?: number;
+  page?: number;
+  total?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * An open envelope for the envelope detail.
+ *
+ * Open on purpose: the detail carries its documents and its whole audit
+ * trail, and the audit trail gains event kinds as the product does. Closing
+ * it would silently drop an event a caller was relying on to know what
+ * happened.
+ *
+ * Nothing secret rides in here: the signer and viewer tokens are the SIGNING
+ * LINK's credentials and the app's detail projection does not include them.
+ */
+export type EnvelopePayload = 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;
+}
+
+/** Send a draft for signature. This EMAILS A REAL PERSON. */
+export interface SendEnvelopeRequest {
+  /** Overrides the envelope's stored message for this send only. */
+  custom_message?: string | null;
+}

package/docs/api/eSignature.md

@@ -0,0 +1,341 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.eSignature`: E-Signature
+
+7 operations (2 read, 1 write, 2 destructive, 2 external).
+
+No hand-written client covers this area. Call it through `g8.api.eSignature.*` 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: [eSignature.d.ts](eSignature.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`createEnvelope`](#op-createenvelope) | `POST /api/v1/envelopes` | write | `quotes:write` | Create Envelope |
+| [`deleteEnvelope`](#op-deleteenvelope) | `DELETE /api/v1/envelopes/{envelope_id}` | destructive | `quotes:delete` | Delete Envelope |
+| [`getEnvelope`](#op-getenvelope) | `GET /api/v1/envelopes/{envelope_id}` | read | `quotes:read` | Get Envelope |
+| [`listEnvelopes`](#op-listenvelopes) | `GET /api/v1/envelopes` | read | `quotes:read` | List Envelopes |
+| [`resendEnvelope`](#op-resendenvelope) | `POST /api/v1/envelopes/{envelope_id}/resend` | external | `quotes:run` | Resend Envelope |
+| [`sendEnvelope`](#op-sendenvelope) | `POST /api/v1/envelopes/{envelope_id}/send` | external | `quotes:run` | Send Envelope |
+| [`voidEnvelope`](#op-voidenvelope) | `POST /api/v1/envelopes/{envelope_id}/void` | destructive | `quotes:delete` | Void Envelope |
+
+---
+
+<a id="op-createenvelope"></a>
+
+### `g8.api.eSignature.createEnvelope(input)`
+
+**Create Envelope**
+
+- HTTP: `POST /api/v1/envelopes`
+- operationId: `create_envelope_envelopes_post` (also callable as `g8.api.call("create_envelope_envelopes_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `quotes:write`
+
+Create a DRAFT envelope. Nothing is emailed.
+
+The documents are HTML the caller already holds - there is no upload step -
+which is what makes the whole flow scriptable. `expires_in_days` counts
+from creation, NOT from the moment it is sent, so a draft left sitting for
+a month has already used its window.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `CreateEnvelopeRequest` | yes | Request body; fields below. |
+
+Body fields (`CreateEnvelopeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.documents` | `Array<EnvelopeDocument>` | yes | At least one document - an empty envelope has nothing to sign. min items 1 |
+| `body.signer_email` | `string` | yes | min length 1 |
+| `body.signer_name` | `string` | yes | min length 1 |
+| `body.subject` | `string` | yes | Subject line the signer sees. min length 1 |
+| `body.expires_in_days` | `integer` | no | How long the signing link stays valid, counted from CREATION rather than from send. default `30`, min 1, max 365 |
+| `body.message` | `string \| null` | no | Covering note in the signing email. |
+| `body.signer_contact_id` | `integer \| null` | no | Link the envelope to a graph8 contact record. |
+| `body.source_id` | `string \| null` | no | The producing record's id. |
+| `body.source_type` | `string \| null` | no | What produced this envelope, e.g. `quote`. Free-form, and filterable on list. |
+
+**Returns** `ApiResponse_EnvelopePayload_`: the envelope `{ data: EnvelopePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.eSignature.createEnvelope({
+  body: {
+    documents: [{ content_html: "example", title: "Example" }],
+    signer_email: "jane@acme.com",
+    signer_name: "Example",
+    subject: "Example",
+  },
+});
+```
+
+---
+
+<a id="op-deleteenvelope"></a>
+
+### `g8.api.eSignature.deleteEnvelope(input)`
+
+**Delete Envelope**
+
+- HTTP: `DELETE /api/v1/envelopes/{envelope_id}`
+- operationId: `delete_envelope_envelopes__envelope_id__delete` (also callable as `g8.api.call("delete_envelope_envelopes__envelope_id__delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `quotes:delete`
+
+Delete a DRAFT envelope.
+
+Drafts only: anything that has been sent comes back as a 400, because a
+document a person has already been asked to sign is evidence and is voided
+rather than removed. The delete is soft and the audit trail survives it.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.envelope_id` | `string` | yes | Envelope id (UUID). |
+
+**Returns** `ApiResponse_EnvelopePayload_`: the envelope `{ data: EnvelopePayload, ... }`. `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.eSignature.deleteEnvelope({ path: { envelope_id: "id" } });
+```
+
+---
+
+<a id="op-getenvelope"></a>
+
+### `g8.api.eSignature.getEnvelope(input)`
+
+**Get Envelope**
+
+- HTTP: `GET /api/v1/envelopes/{envelope_id}`
+- operationId: `get_envelope_envelopes__envelope_id__get` (also callable as `g8.api.call("get_envelope_envelopes__envelope_id__get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `quotes:read`
+
+One envelope, with its documents and its full audit trail.
+
+The audit trail is the answer to "did they actually see it": it records
+when the link was opened, not only when the signature landed.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.envelope_id` | `string` | yes | Envelope id (UUID). |
+
+**Returns** `ApiResponse_EnvelopePayload_`: the envelope `{ data: EnvelopePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+const result = await g8.api.eSignature.getEnvelope({ path: { envelope_id: "id" } });
+```
+
+---
+
+<a id="op-listenvelopes"></a>
+
+### `g8.api.eSignature.listEnvelopes(input?)`
+
+**List Envelopes**
+
+- HTTP: `GET /api/v1/envelopes`
+- operationId: `list_envelopes_envelopes_get` (also callable as `g8.api.call("list_envelopes_envelopes_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `quotes:read`
+
+Envelopes in the organisation, newest first.
+
+`source_type` + `source_id` is the join back to whatever produced the
+envelope, so "has the quote I sent been signed" is one call rather than a
+scan.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.status` | `string \| null` | no | `draft`, `sent`, `viewed`, `completed`, `voided`, `expired`. |
+| `query.source_type` | `string \| null` | no | What produced the envelope, e.g. `quote`. |
+| `query.source_id` | `string \| null` | no | The producing record's id. |
+| `query.page` | `integer` | no | default `1` |
+| `query.limit` | `integer` | no | default `50` |
+
+**Returns** `ApiResponse_EnvelopeListPayload_`: the envelope `{ data: EnvelopeListPayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`EnvelopeListPayload` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `items` | `Array<unknown>` | no |  |
+| `limit` | `integer` | no | default `50` |
+| `page` | `integer` | no | default `1` |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.eSignature.listEnvelopes();
+```
+
+---
+
+<a id="op-resendenvelope"></a>
+
+### `g8.api.eSignature.resendEnvelope(input)`
+
+**Resend Envelope**
+
+- HTTP: `POST /api/v1/envelopes/{envelope_id}/resend`
+- operationId: `resend_envelope_envelopes__envelope_id__resend_post` (also callable as `g8.api.call("resend_envelope_envelopes__envelope_id__resend_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `quotes:run`
+
+Email the signing link again. ALSO REACHES A REAL PERSON.
+
+Only valid while the envelope is `sent` or `viewed` - a draft has never
+been sent and a completed one has nothing left to chase, and both come back
+as a 400 rather than silently doing nothing. The link itself is unchanged,
+so an earlier email still works.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.envelope_id` | `string` | yes | Envelope id (UUID). |
+
+**Returns** `ApiResponse_EnvelopePayload_`: the envelope `{ data: EnvelopePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.eSignature.resendEnvelope({ path: { envelope_id: "id" } });
+```
+
+---
+
+<a id="op-sendenvelope"></a>
+
+### `g8.api.eSignature.sendEnvelope(input)`
+
+**Send Envelope**
+
+- HTTP: `POST /api/v1/envelopes/{envelope_id}/send`
+- operationId: `send_envelope_envelopes__envelope_id__send_post` (also callable as `g8.api.call("send_envelope_envelopes__envelope_id__send_post", input)`)
+- Tier: `external`: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first
+- API-key scope: `quotes:run`
+
+Send the envelope for signature. THIS EMAILS A REAL PERSON.
+
+Not a state change with a side effect - the side effect IS the point: the
+signer gets a link that carries its own credential, and from that moment
+the document is in front of somebody outside the organisation.
+
+Tiered `external` rather than `write` for exactly that reason.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.envelope_id` | `string` | yes | Envelope id (UUID). |
+| `body` | `SendEnvelopeRequest` | no | Request body; fields below. |
+
+Body fields (`SendEnvelopeRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.custom_message` | `string \| null` | no | Overrides the envelope's stored message for this send only. |
+
+**Returns** `ApiResponse_EnvelopePayload_`: the envelope `{ data: EnvelopePayload, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+**Example**
+
+```ts
+// external: reaches real people (sends email/SMS, places a call, launches a send); the SDK never blindly retries it; confirm with a human first.
+const result = await g8.api.eSignature.sendEnvelope({ path: { envelope_id: "id" } });
+```
+
+---
+
+<a id="op-voidenvelope"></a>
+
+### `g8.api.eSignature.voidEnvelope(input)`
+
+**Void Envelope**
+
+- HTTP: `POST /api/v1/envelopes/{envelope_id}/void`
+- operationId: `void_envelope_envelopes__envelope_id__void_post` (also callable as `g8.api.call("void_envelope_envelopes__envelope_id__void_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `quotes:delete`
+
+Cancel an envelope that is already out.
+
+The signing link stops working, so this is the operation to reach for when
+a document was sent in error - deleting it is not, because a sent envelope
+cannot be deleted at all. The audit trail is preserved.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.envelope_id` | `string` | yes | Envelope id (UUID). |
+
+**Returns** `ApiResponse_EnvelopePayload_`: the envelope `{ data: EnvelopePayload, ... }`. `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.eSignature.voidEnvelope({ path: { envelope_id: "id" } });
+```
+
+---
+
+## Referenced types
+
+Named types that appear in the tables above. Full TypeScript definitions: `G8Contract.<Name>` (`import type { G8Contract } from "@graph8/sdk"`).
+
+<a id="type-envelopedocument"></a>
+
+### `EnvelopeDocument`
+
+One document inside an envelope. `content_html` IS the document - there is no upload step and no file. That is why this surface has no multipart endpoint: an envelope is created from HTML the caller already holds, which is what makes it scriptable.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `content_html` | `string` | yes | The document body as HTML. Rendered to the PDF the signer sees. min length 1 |
+| `title` | `string` | yes | min length 1 |