@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/imports.d.ts

@@ -0,0 +1,157 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.imports` (Imports): 3 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"import_contacts_imports__import_id__contacts_post">;
+ *
+ * Reference with examples: imports.md
+ */
+/* eslint-disable */
+
+/** `g8.api.imports.<member>` -> the operationId it calls. */
+export interface ImportsMembers {
+  importContacts: "import_contacts_imports__import_id__contacts_post";
+  previewImportFile: "preview_import_file_imports__import_id__preview_post";
+  uploadImportFile: "upload_import_file_imports_post";
+}
+
+/** Input and output of every `g8.api.imports` operation, keyed by operationId. */
+export interface ImportsOperations {
+  /**
+   * POST /imports/{import_id}/contacts
+   * Import Contacts
+   * tier: write · scope: lists:write
+   */
+  import_contacts_imports__import_id__contacts_post: {
+    input: {
+    path: {
+      /** Id returned by the upload. */
+      import_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ImportContactsRequest;
+  };
+    output: ApiResponse_ImportContactsResponse_;
+  };
+  /**
+   * POST /imports/{import_id}/preview
+   * Preview Import File
+   * tier: read · scope: lists:read
+   */
+  preview_import_file_imports__import_id__preview_post: {
+    input: {
+    path: {
+      /** Id returned by the upload. */
+      import_id: string;
+    };
+    query?: {
+      page?: number;
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body?: Record<string, string>;
+  };
+    output: ApiResponse_DataFilePreviewResponse_;
+  };
+  /**
+   * POST /imports
+   * Upload Import File
+   * tier: write · scope: lists:write
+   */
+  upload_import_file_imports_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_DataFileUploadResponse_;
+  };
+}
+
+// 8 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_DataFilePreviewResponse_ {
+  data: DataFilePreviewResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_DataFileUploadResponse_ {
+  data: DataFileUploadResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ImportContactsResponse_ {
+  data: ImportContactsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+/**
+ * A page of rows as they will be read, with the mapping applied.
+ *
+ * Rows are open dicts: they are the customer's own columns, so there is no
+ * schema to pin.
+ */
+export interface DataFilePreviewResponse {
+  rows?: Array<Record<string, unknown>>;
+  total?: number;
+  [key: string]: unknown;
+}
+
+/**
+ * The stored file, and how many rows it turned out to have.
+ *
+ * `row_count` is the number a caller should budget against: the import
+ * pre-check treats it as the UPPER BOUND on new contacts, so an import is
+ * refused if that many would breach the org's contact limit - even though
+ * some rows will resolve to updates rather than creates.
+ */
+export interface DataFileUploadResponse {
+  /** Detected column headers. */
+  columns?: Array<string>;
+  datafile_id?: string | null;
+  /** Rows detected. The import pre-check budgets against this. */
+  row_count?: number | null;
+  [key: string]: unknown;
+}
+
+/** Import a previously uploaded file's rows as contacts into one list. */
+export interface ImportContactsRequest {
+  /** Source column -> graph8 field. An EMPTY mapping is legal and means the importer falls back to its own header matching, which is why this is not required - but an unmapped column the importer cannot recognise is dropped silently, so preview first. */
+  column_mapping?: Record<string, string>;
+  /** Match imported rows against the graph8 index and fill missing fields - contacts by work email or LinkedIn URL, companies by domain. Off by default because it is extra work the caller may not want on a file they already trust. */
+  enrich_from_graph8?: boolean;
+  /** Audience list the contacts land in. REQUIRED - an import with no destination has nowhere to put the rows, and the caller needs WRITE access to this list, not just read. */
+  list_id: number;
+  /** What happens when a row matches an existing contact. `override` replaces the field; `autofill` only fills one that is currently EMPTY. The default is `override`, matching the app - so an import run without thinking about this WILL overwrite existing data. */
+  update_policy?: "autofill" | "override";
+}
+
+/** What the import actually did. */
+export interface ImportContactsResponse {
+  failed?: number | null;
+  imported?: number | null;
+  list_id?: number | null;
+  skipped?: number | null;
+  updated?: number | null;
+  [key: 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/imports.md

@@ -0,0 +1,174 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.imports`: Imports
+
+3 operations (1 read, 2 write).
+
+No hand-written client covers this area. Call it through `g8.api.imports.*` 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: [imports.d.ts](imports.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`importContacts`](#op-importcontacts) | `POST /api/v1/imports/{import_id}/contacts` | write | `lists:write` | Import Contacts |
+| [`previewImportFile`](#op-previewimportfile) | `POST /api/v1/imports/{import_id}/preview` | read | `lists:read` | Preview Import File |
+| [`uploadImportFile`](#op-uploadimportfile) | `POST /api/v1/imports` | write | `lists:write` | Upload Import File |
+
+---
+
+<a id="op-importcontacts"></a>
+
+### `g8.api.imports.importContacts(input)`
+
+**Import Contacts**
+
+- HTTP: `POST /api/v1/imports/{import_id}/contacts`
+- operationId: `import_contacts_imports__import_id__contacts_post` (also callable as `g8.api.call("import_contacts_imports__import_id__contacts_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Import the file's rows as contacts into a list. THIS WRITES REAL RECORDS.
+
+Two separate authorisations, both resolved for the key's principal and both
+required - neither implies the other:
+
+  * may this caller CREATE contacts at all (`enforce_object_create`);
+  * may they WRITE to this particular list (`verify_list_access`).
+
+`update_policy` defaults to `override`: a row matching an existing contact
+REPLACES that contact's fields rather than only filling blanks. Send
+`autofill` if the file should not win over what is already there.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.import_id` | `string` | yes | Id returned by the upload. |
+| `body` | `ImportContactsRequest` | yes | Request body; fields below. |
+
+Body fields (`ImportContactsRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.list_id` | `integer` | yes | Audience list the contacts land in. REQUIRED - an import with no destination has nowhere to put the rows, and the caller needs WRITE access to this list, not just read. |
+| `body.column_mapping` | `Record<string, string>` | no | Source column -> graph8 field. An EMPTY mapping is legal and means the importer falls back to its own header matching, which is why this is not required - but an unmapped column the importer cannot recognise is dropped silently, so preview first. |
+| `body.enrich_from_graph8` | `boolean` | no | Match imported rows against the graph8 index and fill missing fields - contacts by work email or LinkedIn URL, companies by domain. Off by default because it is extra work the caller may not want on a file they already trust. default `false` |
+| `body.update_policy` | `"autofill" \| "override"` | no | What happens when a row matches an existing contact. `override` replaces the field; `autofill` only fills one that is currently EMPTY. The default is `override`, matching the app - so an import run without thinking about this WILL overwrite existing data. default `"override"` |
+
+**Returns** `ApiResponse_ImportContactsResponse_`: the envelope `{ data: ImportContactsResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`ImportContactsResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `failed` | `integer \| null` | no |  |
+| `imported` | `integer \| null` | no |  |
+| `list_id` | `integer \| null` | no |  |
+| `skipped` | `integer \| null` | no |  |
+| `updated` | `integer \| null` | no |  |
+
+**Example**
+
+```ts
+const result = await g8.api.imports.importContacts({ path: { import_id: "id" }, body: { list_id: 123 } });
+```
+
+---
+
+<a id="op-previewimportfile"></a>
+
+### `g8.api.imports.previewImportFile(input)`
+
+**Preview Import File**
+
+- HTTP: `POST /api/v1/imports/{import_id}/preview`
+- operationId: `preview_import_file_imports__import_id__preview_post` (also callable as `g8.api.call("preview_import_file_imports__import_id__preview_post", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `lists:read`
+
+See how the file will be read, with a mapping applied. Writes nothing.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `path.import_id` | `string` | yes | Id returned by the upload. |
+| `query.page` | `integer` | no | default `1` |
+| `query.limit` | `integer` | no | default `10` |
+| `body` | `Record<string, string>` | no | Request body; fields below. |
+
+**Returns** `ApiResponse_DataFilePreviewResponse_`: the envelope `{ data: DataFilePreviewResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DataFilePreviewResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `rows` | `Array<Record<string, unknown>>` | no |  |
+| `total` | `integer` | no | default `0` |
+
+**Example**
+
+```ts
+const result = await g8.api.imports.previewImportFile({ path: { import_id: "id" } });
+```
+
+---
+
+<a id="op-uploadimportfile"></a>
+
+### `g8.api.imports.uploadImportFile(input?)`
+
+**Upload Import File**
+
+- HTTP: `POST /api/v1/imports`
+- operationId: `upload_import_file_imports_post` (also callable as `g8.api.call("upload_import_file_imports_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `lists:write`
+
+Upload a CSV or Excel file and get back its id and row count.
+
+Nothing is imported by this call - the file is stored and parsed so it can
+be previewed and then imported. The 25 MB ceiling is the app's, enforced by
+reading one byte past it so an exact-boundary file is distinguishable from
+an oversized one even when `Content-Length` is missing or dishonest.
+
+The `row_count` that comes back is what the import pre-check budgets
+against: it is treated as the upper bound on NEW contacts, so an import is
+refused if that many would breach the org's limit, even though some rows
+will resolve to updates.
+
+**Input**: none.
+
+**Returns** `ApiResponse_DataFileUploadResponse_`: the envelope `{ data: DataFileUploadResponse, ... }`. `g8.api` returns the envelope as-is, so read `result.data`.
+
+Other envelope fields: `pagination` (PaginationMeta).
+
+`DataFileUploadResponse` fields:
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `columns` | `Array<string>` | no | Detected column headers. |
+| `datafile_id` | `string \| null` | no |  |
+| `row_count` | `integer \| null` | no | Rows detected. The import pre-check budgets against this. |
+
+**Example**
+
+```ts
+const result = await g8.api.imports.uploadImportFile();
+```