@graph8/sdk 0.251.0 → 0.262.0

package/docs/api/sandbox.d.ts

@@ -0,0 +1,210 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.sandbox` (sandbox): 9 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"sandbox_clear_failure_rules_sandbox_failure_injection_delete">;
+ *
+ * Reference with examples: sandbox.md
+ */
+/* eslint-disable */
+
+/** `g8.api.sandbox.<member>` -> the operationId it calls. */
+export interface SandboxMembers {
+  sandboxClearFailureRules: "sandbox_clear_failure_rules_sandbox_failure_injection_delete";
+  sandboxListFailureRules: "sandbox_list_failure_rules_sandbox_failure_injection_get";
+  sandboxOutbox: "sandbox_outbox_sandbox_outbox_get";
+  sandboxResetFixtures: "sandbox_reset_fixtures_sandbox_fixtures_reset_post";
+  sandboxRestore: "sandbox_restore_sandbox_fixtures_restore_post";
+  sandboxSeedFixtures: "sandbox_seed_fixtures_sandbox_fixtures_seed_post";
+  sandboxSetFailureRule: "sandbox_set_failure_rule_sandbox_failure_injection_put";
+  sandboxSnapshot: "sandbox_snapshot_sandbox_fixtures_snapshot_post";
+  sandboxStatus: "sandbox_status_sandbox_status_get";
+}
+
+/** Input and output of every `g8.api.sandbox` operation, keyed by operationId. */
+export interface SandboxOperations {
+  /**
+   * DELETE /sandbox/failure-injection
+   * Clear failure rules
+   * tier: destructive · scope: sandbox:delete
+   */
+  sandbox_clear_failure_rules_sandbox_failure_injection_delete: {
+    input: {
+    query?: {
+      /** Clear one channel only; omit for all */
+      channel?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: FailureRulesResponse;
+  };
+  /**
+   * GET /sandbox/failure-injection
+   * List failure rules
+   * tier: read · scope: sandbox:read
+   */
+  sandbox_list_failure_rules_sandbox_failure_injection_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: FailureRulesResponse;
+  };
+  /**
+   * GET /sandbox/outbox
+   * List simulated outbox
+   * tier: read · scope: sandbox:read
+   */
+  sandbox_outbox_sandbox_outbox_get: {
+    input: {
+    query?: {
+      /** Filter by channel */
+      channel?: string | null;
+      limit?: number;
+      offset?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: OutboxListResponse;
+  };
+  /**
+   * POST /sandbox/fixtures/reset
+   * Reset fixture data
+   * tier: destructive · scope: sandbox:delete
+   */
+  sandbox_reset_fixtures_sandbox_fixtures_reset_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: FixtureActionResponse;
+  };
+  /**
+   * POST /sandbox/fixtures/restore
+   * Restore a snapshot
+   * tier: destructive · scope: sandbox:delete
+   */
+  sandbox_restore_sandbox_fixtures_restore_post: {
+    input: {
+    query?: {
+      name?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: SnapshotActionResponse;
+  };
+  /**
+   * POST /sandbox/fixtures/seed
+   * Seed sample data
+   * tier: write · scope: sandbox:write
+   */
+  sandbox_seed_fixtures_sandbox_fixtures_seed_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: FixtureActionResponse;
+  };
+  /**
+   * PUT /sandbox/failure-injection
+   * Set a failure rule
+   * tier: write · scope: sandbox:write
+   */
+  sandbox_set_failure_rule_sandbox_failure_injection_put: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: FailureRuleRequest;
+  };
+    output: FailureRulesResponse;
+  };
+  /**
+   * POST /sandbox/fixtures/snapshot
+   * Snapshot fixture tables
+   * tier: write · scope: sandbox:write
+   */
+  sandbox_snapshot_sandbox_fixtures_snapshot_post: {
+    input: {
+    query?: {
+      name?: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: SnapshotActionResponse;
+  };
+  /**
+   * GET /sandbox/status
+   * Sandbox status
+   * tier: read · scope: sandbox:read
+   */
+  sandbox_status_sandbox_status_get: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: SandboxStatusResponse;
+  };
+}
+
+// 6 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface FailureRuleRequest {
+  /** Channel the injected failure applies to: email, sms, whatsapp, voice, linkedin, crm, ads, calendar, or '*' for every channel. */
+  channel: string;
+  /** One of: hard_bounce, provider_error, timeout, rate_limited, invalid_recipient. */
+  failure_mode: string;
+  /** Fail this many sends, then auto-clear. Omit to fail until cleared. */
+  remaining?: number | null;
+}
+
+export interface FailureRulesResponse {
+  rules: Array<Record<string, unknown>>;
+  sandbox?: boolean;
+}
+
+export interface FixtureActionResponse {
+  action: string;
+  companies?: number;
+  contacts?: number;
+  detail?: string | null;
+  sandbox?: boolean;
+}
+
+export interface OutboxListResponse {
+  count: number;
+  items: Array<Record<string, unknown>>;
+  sandbox?: boolean;
+}
+
+export interface SandboxStatusResponse {
+  /** Which graph8 deployment answered: 'sandbox' (developer sandbox), 'qa' (the QA environment) or 'live' (production). */
+  environment?: string;
+  /** Mode of the API key that made the call: 'live', 'test' or 'sandbox'. */
+  key_mode?: string | null;
+  message: string;
+  org_id: string;
+  sandbox?: boolean;
+}
+
+export interface SnapshotActionResponse {
+  action: string;
+  name: string;
+  sandbox?: boolean;
+  tables: Array<string>;
+}

package/docs/api/sandbox.md

@@ -0,0 +1,380 @@
+<!-- Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. -->
+
+# `g8.api.sandbox`: sandbox
+
+9 operations (3 read, 3 write, 3 destructive).
+
+No hand-written client covers this area. Call it through `g8.api.sandbox.*` 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: [sandbox.d.ts](sandbox.d.ts).
+
+## Operations
+
+| Call | HTTP | Tier | Scope | Summary |
+|---|---|---|---|---|
+| [`sandboxClearFailureRules`](#op-sandboxclearfailurerules) | `DELETE /api/v1/sandbox/failure-injection` | destructive | `sandbox:delete` | Clear failure rules |
+| [`sandboxListFailureRules`](#op-sandboxlistfailurerules) | `GET /api/v1/sandbox/failure-injection` | read | `sandbox:read` | List failure rules |
+| [`sandboxOutbox`](#op-sandboxoutbox) | `GET /api/v1/sandbox/outbox` | read | `sandbox:read` | List simulated outbox |
+| [`sandboxResetFixtures`](#op-sandboxresetfixtures) | `POST /api/v1/sandbox/fixtures/reset` | destructive | `sandbox:delete` | Reset fixture data |
+| [`sandboxRestore`](#op-sandboxrestore) | `POST /api/v1/sandbox/fixtures/restore` | destructive | `sandbox:delete` | Restore a snapshot |
+| [`sandboxSeedFixtures`](#op-sandboxseedfixtures) | `POST /api/v1/sandbox/fixtures/seed` | write | `sandbox:write` | Seed sample data |
+| [`sandboxSetFailureRule`](#op-sandboxsetfailurerule) | `PUT /api/v1/sandbox/failure-injection` | write | `sandbox:write` | Set a failure rule |
+| [`sandboxSnapshot`](#op-sandboxsnapshot) | `POST /api/v1/sandbox/fixtures/snapshot` | write | `sandbox:write` | Snapshot fixture tables |
+| [`sandboxStatus`](#op-sandboxstatus) | `GET /api/v1/sandbox/status` | read | `sandbox:read` | Sandbox status |
+
+---
+
+<a id="op-sandboxclearfailurerules"></a>
+
+### `g8.api.sandbox.sandboxClearFailureRules(input?)`
+
+**Clear failure rules**
+
+- HTTP: `DELETE /api/v1/sandbox/failure-injection`
+- operationId: `sandbox_clear_failure_rules_sandbox_failure_injection_delete` (also callable as `g8.api.call("sandbox_clear_failure_rules_sandbox_failure_injection_delete", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `sandbox:delete`
+- Sandbox only: available to test-mode keys against the sandbox environment
+
+SANDBOX ONLY. This endpoint exists only in the graph8 developer sandbox and returns 404 on the live platform. Call GET /sandbox/status to see which environment your key reaches.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.channel` | `string \| null` | no | Clear one channel only; omit for all |
+
+**Returns** `FailureRulesResponse`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `rules` | `Array<Record<string, unknown>>` | yes |  |
+| `sandbox` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.sandbox.sandboxClearFailureRules();
+```
+
+---
+
+<a id="op-sandboxlistfailurerules"></a>
+
+### `g8.api.sandbox.sandboxListFailureRules(input?)`
+
+**List failure rules**
+
+- HTTP: `GET /api/v1/sandbox/failure-injection`
+- operationId: `sandbox_list_failure_rules_sandbox_failure_injection_get` (also callable as `g8.api.call("sandbox_list_failure_rules_sandbox_failure_injection_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `sandbox:read`
+- Sandbox only: available to test-mode keys against the sandbox environment
+
+SANDBOX ONLY. This endpoint exists only in the graph8 developer sandbox and returns 404 on the live platform. Call GET /sandbox/status to see which environment your key reaches.
+
+**Input**: none.
+
+**Returns** `FailureRulesResponse`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `rules` | `Array<Record<string, unknown>>` | yes |  |
+| `sandbox` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+const result = await g8.api.sandbox.sandboxListFailureRules();
+```
+
+---
+
+<a id="op-sandboxoutbox"></a>
+
+### `g8.api.sandbox.sandboxOutbox(input?)`
+
+**List simulated outbox**
+
+- HTTP: `GET /api/v1/sandbox/outbox`
+- operationId: `sandbox_outbox_sandbox_outbox_get` (also callable as `g8.api.call("sandbox_outbox_sandbox_outbox_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `sandbox:read`
+- Sandbox only: available to test-mode keys against the sandbox environment
+
+SANDBOX ONLY. This endpoint exists only in the graph8 developer sandbox and returns 404 on the live platform. Call GET /sandbox/status to see which environment your key reaches.
+
+Every simulated outbound side effect for your org, newest first.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.channel` | `string \| null` | no | Filter by channel |
+| `query.limit` | `integer` | no | default `50` |
+| `query.offset` | `integer` | no | default `0` |
+
+**Returns** `OutboxListResponse`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `count` | `integer` | yes |  |
+| `items` | `Array<Record<string, unknown>>` | yes |  |
+| `sandbox` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+const result = await g8.api.sandbox.sandboxOutbox();
+```
+
+---
+
+<a id="op-sandboxresetfixtures"></a>
+
+### `g8.api.sandbox.sandboxResetFixtures(input?)`
+
+**Reset fixture data**
+
+- HTTP: `POST /api/v1/sandbox/fixtures/reset`
+- operationId: `sandbox_reset_fixtures_sandbox_fixtures_reset_post` (also callable as `g8.api.call("sandbox_reset_fixtures_sandbox_fixtures_reset_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `sandbox:delete`
+- Sandbox only: available to test-mode keys against the sandbox environment
+
+SANDBOX ONLY. This endpoint exists only in the graph8 developer sandbox and returns 404 on the live platform. Call GET /sandbox/status to see which environment your key reaches.
+
+Delete all seeded fixture rows for your org and reseed a fresh set.
+
+**Input**: none.
+
+**Returns** `FixtureActionResponse`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | yes |  |
+| `companies` | `integer` | no | default `0` |
+| `contacts` | `integer` | no | default `0` |
+| `detail` | `string \| null` | no |  |
+| `sandbox` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.sandbox.sandboxResetFixtures();
+```
+
+---
+
+<a id="op-sandboxrestore"></a>
+
+### `g8.api.sandbox.sandboxRestore(input?)`
+
+**Restore a snapshot**
+
+- HTTP: `POST /api/v1/sandbox/fixtures/restore`
+- operationId: `sandbox_restore_sandbox_fixtures_restore_post` (also callable as `g8.api.call("sandbox_restore_sandbox_fixtures_restore_post", input)`)
+- Tier: `destructive`: deletes or archives data; confirm with a human before calling
+- API-key scope: `sandbox:delete`
+- Sandbox only: available to test-mode keys against the sandbox environment
+
+SANDBOX ONLY. This endpoint exists only in the graph8 developer sandbox and returns 404 on the live platform. Call GET /sandbox/status to see which environment your key reaches.
+
+Restore the fixture rows to a previously saved snapshot.
+
+Only sandbox-fixture rows (``meta.sandbox_fixture = true``) are replaced —
+any records you created through normal API calls in this sandbox are left
+untouched. Snapshots are taken over the same fixture-scoped set, so a
+restore round-trips exactly what ``/fixtures/snapshot`` captured.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.name` | `string` | no | default `"default"` |
+
+**Returns** `SnapshotActionResponse`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `tables` | `Array<string>` | yes |  |
+| `sandbox` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+// destructive: deletes or archives data; confirm with a human before calling.
+const result = await g8.api.sandbox.sandboxRestore();
+```
+
+---
+
+<a id="op-sandboxseedfixtures"></a>
+
+### `g8.api.sandbox.sandboxSeedFixtures(input?)`
+
+**Seed sample data**
+
+- HTTP: `POST /api/v1/sandbox/fixtures/seed`
+- operationId: `sandbox_seed_fixtures_sandbox_fixtures_seed_post` (also callable as `g8.api.call("sandbox_seed_fixtures_sandbox_fixtures_seed_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `sandbox:write`
+- Sandbox only: available to test-mode keys against the sandbox environment
+
+SANDBOX ONLY. This endpoint exists only in the graph8 developer sandbox and returns 404 on the live platform. Call GET /sandbox/status to see which environment your key reaches.
+
+Insert the standard sandbox fixture set into your org. Idempotent.
+
+**Input**: none.
+
+**Returns** `FixtureActionResponse`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | yes |  |
+| `companies` | `integer` | no | default `0` |
+| `contacts` | `integer` | no | default `0` |
+| `detail` | `string \| null` | no |  |
+| `sandbox` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+const result = await g8.api.sandbox.sandboxSeedFixtures();
+```
+
+---
+
+<a id="op-sandboxsetfailurerule"></a>
+
+### `g8.api.sandbox.sandboxSetFailureRule(input)`
+
+**Set a failure rule**
+
+- HTTP: `PUT /api/v1/sandbox/failure-injection`
+- operationId: `sandbox_set_failure_rule_sandbox_failure_injection_put` (also callable as `g8.api.call("sandbox_set_failure_rule_sandbox_failure_injection_put", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `sandbox:write`
+- Sandbox only: available to test-mode keys against the sandbox environment
+
+SANDBOX ONLY. This endpoint exists only in the graph8 developer sandbox and returns 404 on the live platform. Call GET /sandbox/status to see which environment your key reaches.
+
+Make the next simulated sends on a channel fail the way you choose (M3-5).
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body` | `FailureRuleRequest` | yes | Request body; fields below. |
+
+Body fields (`FailureRuleRequest`):
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `body.channel` | `string` | yes | Channel the injected failure applies to: email, sms, whatsapp, voice, linkedin, crm, ads, calendar, or '*' for every channel. |
+| `body.failure_mode` | `string` | yes | One of: hard_bounce, provider_error, timeout, rate_limited, invalid_recipient. |
+| `body.remaining` | `integer \| null` | no | Fail this many sends, then auto-clear. Omit to fail until cleared. min 1, max 10000 |
+
+**Returns** `FailureRulesResponse`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `rules` | `Array<Record<string, unknown>>` | yes |  |
+| `sandbox` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+const result = await g8.api.sandbox.sandboxSetFailureRule({ body: { channel: "example", failure_mode: "example" } });
+```
+
+---
+
+<a id="op-sandboxsnapshot"></a>
+
+### `g8.api.sandbox.sandboxSnapshot(input?)`
+
+**Snapshot fixture tables**
+
+- HTTP: `POST /api/v1/sandbox/fixtures/snapshot`
+- operationId: `sandbox_snapshot_sandbox_fixtures_snapshot_post` (also callable as `g8.api.call("sandbox_snapshot_sandbox_fixtures_snapshot_post", input)`)
+- Tier: `write`: creates or changes records; the SDK sends an Idempotency-Key and retries transient failures
+- API-key scope: `sandbox:write`
+- Sandbox only: available to test-mode keys against the sandbox environment
+
+SANDBOX ONLY. This endpoint exists only in the graph8 developer sandbox and returns 404 on the live platform. Call GET /sandbox/status to see which environment your key reaches.
+
+Save the current contents of the fixture tables under a named snapshot.
+
+**Input**
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `query.name` | `string` | no | default `"default"` |
+
+**Returns** `SnapshotActionResponse`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `action` | `string` | yes |  |
+| `name` | `string` | yes |  |
+| `tables` | `Array<string>` | yes |  |
+| `sandbox` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+const result = await g8.api.sandbox.sandboxSnapshot();
+```
+
+---
+
+<a id="op-sandboxstatus"></a>
+
+### `g8.api.sandbox.sandboxStatus(input?)`
+
+**Sandbox status**
+
+- HTTP: `GET /api/v1/sandbox/status`
+- operationId: `sandbox_status_sandbox_status_get` (also callable as `g8.api.call("sandbox_status_sandbox_status_get", input)`)
+- Tier: `read`: reads data; safe to call and to retry
+- API-key scope: `sandbox:read`
+
+Report whether this is the developer sandbox and which org the key acts as.
+
+Answers on every deployment. In the developer sandbox: ``sandbox: true``,
+``environment: "sandbox"``. Anywhere else: ``sandbox: false`` and
+``environment`` is ``"live"`` (production) or ``"qa"``. The other
+``/sandbox/*`` routes exist only in the sandbox and return 404 elsewhere.
+
+**Input**: none.
+
+**Returns** `SandboxStatusResponse`.
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `message` | `string` | yes |  |
+| `org_id` | `string` | yes |  |
+| `environment` | `string` | no | Which graph8 deployment answered: 'sandbox' (developer sandbox), 'qa' (the QA environment) or 'live' (production). default `"sandbox"` |
+| `key_mode` | `string \| null` | no | Mode of the API key that made the call: 'live', 'test' or 'sandbox'. |
+| `sandbox` | `boolean` | no | default `true` |
+
+**Example**
+
+```ts
+const result = await g8.api.sandbox.sandboxStatus();
+```

package/docs/api/scans.d.ts

@@ -0,0 +1,104 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.scans` (Scans): 2 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_scan_repos__repo_id__scan_post">;
+ *
+ * Reference with examples: scans.md
+ */
+/* eslint-disable */
+
+/** `g8.api.scans.<member>` -> the operationId it calls. */
+export interface ScansMembers {
+  createScan: "create_scan_repos__repo_id__scan_post";
+  getScan: "get_scan_repos__repo_id__scan_get";
+}
+
+/** Input and output of every `g8.api.scans` operation, keyed by operationId. */
+export interface ScansOperations {
+  /**
+   * POST /repos/{repo_id}/scan
+   * Create Scan
+   * tier: billable · scope: search:run
+   */
+  create_scan_repos__repo_id__scan_post: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ScanResultsRequest;
+  };
+    output: ApiResponse_ScanResponse_;
+  };
+  /**
+   * GET /repos/{repo_id}/scan
+   * Get Scan
+   * tier: billable · scope: search:run
+   */
+  get_scan_repos__repo_id__scan_get: {
+    input: {
+    path: {
+      /** Repository ID */
+      repo_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ScanResponse_;
+  };
+}
+
+// 4 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_ScanResponse_ {
+  data: ScanResponse;
+  pagination?: PaginationMeta | null;
+}
+
+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;
+}
+
+export interface ScanResponse {
+  api_routes: Array<Record<string, unknown>>;
+  created_at?: string | null;
+  gtm_readiness?: Record<string, unknown>;
+  id: string;
+  product_type?: string | null;
+  readme_summary?: string | null;
+  repo_id: string;
+  scan_duration_ms?: number | null;
+  tech_stack: Record<string, unknown>;
+}
+
+export interface ScanResultsRequest {
+  /** Detected API routes */
+  api_routes?: Array<Record<string, unknown>>;
+  /** GTM readiness flags */
+  gtm_readiness?: Record<string, unknown>;
+  /** Detected product type (b2b_saas, api, etc.) */
+  product_type?: string | null;
+  /** Extracted README summary */
+  readme_summary?: string | null;
+  /** Scan duration in milliseconds */
+  scan_duration_ms?: number | null;
+  /** Detected tech stack (framework, language, etc.) */
+  tech_stack: Record<string, unknown>;
+}