@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/appObjects.d.ts

@@ -0,0 +1,415 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.appObjects` (App Objects): 10 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"create_app_object_record_app_objects__object_slug__records_post">;
+ *
+ * Reference with examples: appObjects.md
+ */
+/* eslint-disable */
+
+/** `g8.api.appObjects.<member>` -> the operationId it calls. */
+export interface AppObjectsMembers {
+  createAppObjectRecord: "create_app_object_record_app_objects__object_slug__records_post";
+  getAppObject: "get_app_object_app_objects__object_slug__get";
+  getAppObjectRecord: "get_app_object_record_app_objects__object_slug__records__record_id__get";
+  getAppObjectRecordChanges: "get_app_object_record_changes_app_objects__object_slug__records__record_id__changes_get";
+  getAppObjectRecordHistory: "get_app_object_record_history_app_objects__object_slug__records__record_id__history_get";
+  listAppObjectAttributes: "list_app_object_attributes_app_objects__object_slug__attributes_get";
+  listAppObjectRecords: "list_app_object_records_app_objects__object_slug__records_get";
+  listAppObjects: "list_app_objects_app_objects_get";
+  restoreAppObjectRecord: "restore_app_object_record_app_objects__object_slug__records__record_id__restore_post";
+  updateAppObjectRecord: "update_app_object_record_app_objects__object_slug__records__record_id__patch";
+}
+
+/** Input and output of every `g8.api.appObjects` operation, keyed by operationId. */
+export interface AppObjectsOperations {
+  /**
+   * POST /app/objects/{object_slug}/records
+   * Create App Object Record
+   * tier: write · scope: n/a
+   */
+  create_app_object_record_app_objects__object_slug__records_post: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      Origin?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RecordWriteRequest;
+  };
+    output: ApiResponse_ObjectRecordResponse_;
+  };
+  /**
+   * GET /app/objects/{object_slug}
+   * Get App Object
+   * tier: read · scope: n/a
+   */
+  get_app_object_app_objects__object_slug__get: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      Origin?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ObjectDefinitionResponse_;
+  };
+  /**
+   * GET /app/objects/{object_slug}/records/{record_id}
+   * Get App Object Record
+   * tier: read · scope: n/a
+   */
+  get_app_object_record_app_objects__object_slug__records__record_id__get: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    headers?: {
+      Origin?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ObjectRecordResponse_;
+  };
+  /**
+   * GET /app/objects/{object_slug}/records/{record_id}/changes
+   * Get App Object Record Changes
+   * tier: read · scope: n/a
+   */
+  get_app_object_record_changes_app_objects__object_slug__records__record_id__changes_get: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    query?: {
+      limit?: number;
+      cursor?: string | null;
+    };
+    headers?: {
+      Origin?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RecordMutationsResponse_;
+  };
+  /**
+   * GET /app/objects/{object_slug}/records/{record_id}/history
+   * Get App Object Record History
+   * tier: read · scope: n/a
+   */
+  get_app_object_record_history_app_objects__object_slug__records__record_id__history_get: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    query?: {
+      /** Maximum generations to return */
+      limit?: number;
+    };
+    headers?: {
+      Origin?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RecordHistoryResponse_;
+  };
+  /**
+   * GET /app/objects/{object_slug}/attributes
+   * List App Object Attributes
+   * tier: read · scope: n/a
+   */
+  list_app_object_attributes_app_objects__object_slug__attributes_get: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      Origin?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_AttributeDefinitionResponse__;
+  };
+  /**
+   * GET /app/objects/{object_slug}/records
+   * List App Object Records
+   * tier: read · scope: n/a
+   */
+  list_app_object_records_app_objects__object_slug__records_get: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    query?: {
+      /** Page number (ignored when `cursor` is supplied) */
+      page?: number;
+      /** Items per page */
+      limit?: number;
+      /** Opaque cursor from a prior response. Takes precedence over `page`. */
+      cursor?: string | null;
+    };
+    headers?: {
+      Origin?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_ObjectRecordResponse__;
+  };
+  /**
+   * GET /app/objects
+   * List App Objects
+   * tier: read · scope: n/a
+   */
+  list_app_objects_app_objects_get: {
+    input: {
+    headers?: {
+      Origin?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_ObjectDefinitionResponse__;
+  };
+  /**
+   * POST /app/objects/{object_slug}/records/{record_id}/restore
+   * Restore App Object Record
+   * tier: write · scope: n/a
+   */
+  restore_app_object_record_app_objects__object_slug__records__record_id__restore_post: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    headers?: {
+      Origin?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ObjectRecordResponse_;
+  };
+  /**
+   * PATCH /app/objects/{object_slug}/records/{record_id}
+   * Update App Object Record
+   * tier: write · scope: n/a
+   */
+  update_app_object_record_app_objects__object_slug__records__record_id__patch: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    headers?: {
+      Origin?: string | null;
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RecordUpdateRequest;
+  };
+    output: ApiResponse_ObjectRecordResponse_;
+  };
+}
+
+// 18 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_ObjectDefinitionResponse_ {
+  data: ObjectDefinitionResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_ObjectRecordResponse_ {
+  data: ObjectRecordResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_RecordHistoryResponse_ {
+  data: RecordHistoryResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_RecordMutationsResponse_ {
+  data: RecordMutationsResponse;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_AttributeDefinitionResponse__ {
+  data: Array<AttributeDefinitionResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_ObjectDefinitionResponse__ {
+  data: Array<ObjectDefinitionResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+export interface ApiResponse_list_ObjectRecordResponse__ {
+  data: Array<ObjectRecordResponse>;
+  pagination?: PaginationMeta | null;
+}
+
+/** One field on a custom object, and the rules its values must satisfy. */
+export interface AttributeDefinitionResponse {
+  /** One of the 16 supported attribute types (`text`, `number`, `email_address`, `timestamp`, `select`, `record_reference`, …). Determines how values are validated and canonicalized. */
+  attribute_type: string;
+  /** Type-specific configuration, e.g. select options. Record references require target_object and must resolve to active records in that object within the caller's organization and app. */
+  config?: Record<string, unknown>;
+  /** Configured create default. Enabled non-null defaults pass the same validation as explicit values. */
+  default_value?: unknown;
+  /** Customer-configured description of the field. */
+  description?: string | null;
+  /** Archived fields retain their values and can be restored. */
+  is_archived?: boolean;
+  /** Apply the configured default when this field is omitted on create. Never applies on PATCH. */
+  is_default_value_enabled?: boolean;
+  /** Values are a list rather than a scalar. */
+  is_multiselect?: boolean;
+  /** Required on create. PATCH may omit it, but cannot clear it with null or an empty multivalue list. */
+  is_required?: boolean;
+  /** Whether this field is protected as a system attribute. */
+  is_system?: boolean;
+  /** No two active records may hold the same value for this attribute. A collision is rejected with `409 duplicate_active_value`. */
+  is_unique?: boolean;
+  /** Stable API slug for the attribute, used as a payload key. */
+  slug: string;
+  /** Configured display order; equal values are ordered by API slug. */
+  sort_order?: number;
+  /** Customer-facing field label, distinct from its stable API slug. */
+  title: string;
+}
+
+/** One custom object type in the caller's workspace. */
+export interface ObjectDefinitionResponse {
+  /** Customer-configured object description. */
+  description?: string | null;
+  /** Active single-value field used to label records; null uses the default. */
+  display_attribute_slug?: string | null;
+  /** Configured graph8 icon name; null uses the default. */
+  icon?: string | null;
+  /** Archived objects are hidden from listings. */
+  is_archived?: boolean;
+  /** True for objects graph8 ships; system objects cannot be deleted. */
+  is_system?: boolean;
+  /** Display name for many records, e.g. "Invoices". */
+  plural_noun: string;
+  /** Display name for one record, e.g. "Invoice". */
+  singular_noun: string;
+  /** Stable API slug for the object type, e.g. `invoices`. */
+  slug: string;
+}
+
+/** One record, with its currently active attribute values. */
+export interface ObjectRecordResponse {
+  created_at?: string | null;
+  /** Opaque record identifier. */
+  id: string;
+  /** Archived records are excluded from listings. */
+  is_archived?: boolean;
+  /** The object type this record belongs to. */
+  object_slug: string;
+  /** Record revision for conditional updates. */
+  revision?: number;
+  updated_at?: string | null;
+  /** Currently active values, keyed by attribute slug. Shapes follow each attribute's own type; call `GET /objects/{object_slug}/attributes` for the schema. */
+  values?: 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;
+}
+
+/**
+ * One generation of one attribute's value.
+ *
+ * Values are TEMPORAL rather than mutable: setting a new value closes the
+ * previous generation and opens a new one, so history is the natural reading of
+ * the store rather than a separate log that could drift from it. An entry with
+ * a null `active_until` is the value currently in force.
+ */
+export interface RecordHistoryEntry {
+  /** When this value took effect. */
+  active_from?: string | null;
+  /** When it was superseded. Null means it is still in force. */
+  active_until?: string | null;
+  /** Opaque id of whoever set it. */
+  actor_id?: string | null;
+  /** Attribute slug this generation belongs to. */
+  attribute: string;
+  /** The value held during this generation. */
+  value?: unknown;
+}
+
+/** A record's value timeline, newest first. */
+export interface RecordHistoryResponse {
+  entries?: Array<RecordHistoryEntry>;
+  record_id: string;
+}
+
+export interface RecordMutationEntry {
+  action: "created" | "updated" | "archived" | "restored";
+  actor_id: string | null;
+  actor_type: "user" | "api" | "app" | "integration" | "system";
+  app_id?: string | null;
+  changes: Record<string, RecordMutationValueChange>;
+  id: string;
+  is_archived: boolean;
+  occurred_at: string;
+  revision: number;
+  source: string;
+  was_archived: boolean;
+}
+
+export interface RecordMutationValueChange {
+  after?: unknown;
+  after_present: boolean;
+  before?: unknown;
+  before_present: boolean;
+}
+
+/** Immutable mutation facts, newest first, with a stable forward cursor. */
+export interface RecordMutationsResponse {
+  entries: Array<RecordMutationEntry>;
+  next_cursor?: string | null;
+  record_id: string;
+}
+
+export interface RecordUpdateRequest {
+  /** Append canonical non-duplicate values to multivalue fields. Fields must not overlap values or remove_values. */
+  append_values?: Record<string, Array<unknown>>;
+  /** Required for canonical contact or company PATCH. Apply only if the record still has this revision; otherwise return 409. */
+  expected_revision?: number | null;
+  /** Remove all canonical matches from multivalue fields. Fields must not overlap values or append_values. */
+  remove_values?: Record<string, Array<unknown>>;
+  /** Attribute values keyed by slug. Call `GET /objects/{object_slug}/attributes` for active fields. Canonical contacts and companies retain CONTACT_*, COMPANY_* and udo_* field names. Unknown keys are rejected with 422. PATCH preserves omitted fields; required fields cannot be cleared with null or an empty multivalue list. Record references must resolve to active records of their configured target object in the same organization and app. */
+  values?: Record<string, unknown>;
+}
+
+/**
+ * A record payload: attribute slugs to values.
+ *
+ * Untyped by necessity — the valid keys and value shapes come from the
+ * customer's own attribute definitions at runtime. Every key is validated
+ * against those definitions before anything is written, and an unrecognised one
+ * is a 422 rather than a silent drop.
+ */
+export interface RecordWriteRequest {
+  /** Attribute values keyed by slug. Call `GET /objects/{object_slug}/attributes` for active fields. Canonical contacts and companies retain CONTACT_*, COMPANY_* and udo_* field names. Unknown keys are rejected with 422. PATCH preserves omitted fields; required fields cannot be cleared with null or an empty multivalue list. Record references must resolve to active records of their configured target object in the same organization and app. */
+  values?: Record<string, unknown>;
+}