@graph8/sdk 0.251.0 → 0.260.0

package/docs/api/objects.d.ts

@@ -0,0 +1,621 @@
+/* Generated by sdk/js/scripts/generate-agent-docs.ts from developer-contract/openapi.json. Regenerated on every build. */
+
+/**
+ * Types for `g8.api.objects` (Objects): 18 operations.
+ *
+ * For reading. In code, import from the package instead:
+ *   import type { ApiInput, ApiOutput, G8Contract } from "@graph8/sdk";
+ *   type In = ApiInput<"archive_attribute_objects__object_slug__attributes__attr_slug__delete">;
+ *
+ * Reference with examples: objects.md
+ */
+/* eslint-disable */
+
+/** `g8.api.objects.<member>` -> the operationId it calls. */
+export interface ObjectsMembers {
+  archiveAttribute: "archive_attribute_objects__object_slug__attributes__attr_slug__delete";
+  archiveObject: "archive_object_objects__object_slug__delete";
+  archiveObjectRecord: "archive_object_record_objects__object_slug__records__record_id__delete";
+  createAttribute: "create_attribute_objects__object_slug__attributes_post";
+  createObject: "create_object_objects_post";
+  createObjectRecord: "create_object_record_objects__object_slug__records_post";
+  getObject: "get_object_objects__object_slug__get";
+  getObjectRecord: "get_object_record_objects__object_slug__records__record_id__get";
+  getObjectRecordChanges: "get_object_record_changes_objects__object_slug__records__record_id__changes_get";
+  getObjectRecordHistory: "get_object_record_history_objects__object_slug__records__record_id__history_get";
+  listObjectAttributes: "list_object_attributes_objects__object_slug__attributes_get";
+  listObjectRecords: "list_object_records_objects__object_slug__records_get";
+  listObjects: "list_objects_objects_get";
+  restoreObjectRecord: "restore_object_record_objects__object_slug__records__record_id__restore_post";
+  updateAttribute: "update_attribute_objects__object_slug__attributes__attr_slug__patch";
+  updateObject: "update_object_objects__object_slug__patch";
+  updateObjectRecord: "update_object_record_objects__object_slug__records__record_id__patch";
+  upsertObjectRecord: "upsert_object_record_objects__object_slug__records_upsert_post";
+}
+
+/** Input and output of every `g8.api.objects` operation, keyed by operationId. */
+export interface ObjectsOperations {
+  /**
+   * DELETE /objects/{object_slug}/attributes/{attr_slug}
+   * Archive Attribute
+   * tier: destructive · scope: objects:manage
+   */
+  archive_attribute_objects__object_slug__attributes__attr_slug__delete: {
+    input: {
+    path: {
+      object_slug: string;
+      attr_slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_AttributeDefinitionResponse_;
+  };
+  /**
+   * DELETE /objects/{object_slug}
+   * Archive Object
+   * tier: destructive · scope: objects:manage
+   */
+  archive_object_objects__object_slug__delete: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ObjectDefinitionResponse_;
+  };
+  /**
+   * DELETE /objects/{object_slug}/records/{record_id}
+   * Archive Object Record
+   * tier: destructive · scope: objects:delete
+   */
+  archive_object_record_objects__object_slug__records__record_id__delete: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ObjectRecordResponse_;
+  };
+  /**
+   * POST /objects/{object_slug}/attributes
+   * Create Attribute
+   * tier: write · scope: objects:manage
+   */
+  create_attribute_objects__object_slug__attributes_post: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AttributeCreateRequest;
+  };
+    output: ApiResponse_AttributeDefinitionResponse_;
+  };
+  /**
+   * POST /objects
+   * Create Object
+   * tier: write · scope: objects:manage
+   */
+  create_object_objects_post: {
+    input: {
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ObjectCreateRequest;
+  };
+    output: ApiResponse_ObjectDefinitionResponse_;
+  };
+  /**
+   * POST /objects/{object_slug}/records
+   * Create Object Record
+   * tier: write · scope: objects:write
+   */
+  create_object_record_objects__object_slug__records_post: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RecordWriteRequest;
+  };
+    output: ApiResponse_ObjectRecordResponse_;
+  };
+  /**
+   * GET /objects/{object_slug}
+   * Get Object
+   * tier: read · scope: objects:read
+   */
+  get_object_objects__object_slug__get: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ObjectDefinitionResponse_;
+  };
+  /**
+   * GET /objects/{object_slug}/records/{record_id}
+   * Get Object Record
+   * tier: read · scope: objects:read
+   */
+  get_object_record_objects__object_slug__records__record_id__get: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ObjectRecordResponse_;
+  };
+  /**
+   * GET /objects/{object_slug}/records/{record_id}/changes
+   * Get Object Record Changes
+   * tier: read · scope: objects:read
+   */
+  get_object_record_changes_objects__object_slug__records__record_id__changes_get: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    query?: {
+      limit?: number;
+      cursor?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RecordMutationsResponse_;
+  };
+  /**
+   * GET /objects/{object_slug}/records/{record_id}/history
+   * Get Object Record History
+   * tier: read · scope: objects:read
+   */
+  get_object_record_history_objects__object_slug__records__record_id__history_get: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    query?: {
+      /** Maximum generations to return */
+      limit?: number;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_RecordHistoryResponse_;
+  };
+  /**
+   * GET /objects/{object_slug}/attributes
+   * List Object Attributes
+   * tier: read · scope: objects:read
+   */
+  list_object_attributes_objects__object_slug__attributes_get: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    query?: {
+      include_archived?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_AttributeDefinitionResponse__;
+  };
+  /**
+   * GET /objects/{object_slug}/records
+   * List Object Records
+   * tier: read · scope: objects:read
+   */
+  list_object_records_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 pagination cursor from a prior response's `next_cursor`. When supplied it takes precedence over `page`. */
+      cursor?: string | null;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_ObjectRecordResponse__;
+  };
+  /**
+   * GET /objects
+   * List Objects
+   * tier: read · scope: objects:read
+   */
+  list_objects_objects_get: {
+    input: {
+    query?: {
+      include_archived?: boolean;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_list_ObjectDefinitionResponse__;
+  };
+  /**
+   * POST /objects/{object_slug}/records/{record_id}/restore
+   * Restore Object Record
+   * tier: write · scope: objects:write
+   */
+  restore_object_record_objects__object_slug__records__record_id__restore_post: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+  };
+    output: ApiResponse_ObjectRecordResponse_;
+  };
+  /**
+   * PATCH /objects/{object_slug}/attributes/{attr_slug}
+   * Update Attribute
+   * tier: write · scope: objects:manage
+   */
+  update_attribute_objects__object_slug__attributes__attr_slug__patch: {
+    input: {
+    path: {
+      object_slug: string;
+      attr_slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: AttributeUpdateRequest;
+  };
+    output: ApiResponse_AttributeDefinitionResponse_;
+  };
+  /**
+   * PATCH /objects/{object_slug}
+   * Update Object
+   * tier: write · scope: objects:manage
+   */
+  update_object_objects__object_slug__patch: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: ObjectUpdateRequest;
+  };
+    output: ApiResponse_ObjectDefinitionResponse_;
+  };
+  /**
+   * PATCH /objects/{object_slug}/records/{record_id}
+   * Update Object Record
+   * tier: write · scope: objects:write
+   */
+  update_object_record_objects__object_slug__records__record_id__patch: {
+    input: {
+    path: {
+      object_slug: string;
+      record_id: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RecordUpdateRequest;
+  };
+    output: ApiResponse_ObjectRecordResponse_;
+  };
+  /**
+   * POST /objects/{object_slug}/records/upsert
+   * Upsert Object Record
+   * tier: write · scope: objects:write
+   */
+  upsert_object_record_objects__object_slug__records_upsert_post: {
+    input: {
+    path: {
+      object_slug: string;
+    };
+    headers?: {
+      "X-Target-Org-Id"?: string | null;
+    };
+    body: RecordUpsertRequest;
+  };
+    output: ApiResponse_ObjectRecordResponse_;
+  };
+}
+
+// 26 schemas referenced above (the same as G8Contract.<Name>).
+
+export interface ApiResponse_AttributeDefinitionResponse_ {
+  data: AttributeDefinitionResponse;
+  pagination?: PaginationMeta | null;
+}
+
+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;
+}
+
+/** Configuration for specific attribute types. */
+export interface AttributeConfig {
+  currency_code?: string | null;
+  max_value?: number | null;
+  options?: Array<Record<string, unknown>> | null;
+  referenced_object?: string | null;
+  target_object?: string | null;
+}
+
+export interface AttributeCreateRequest {
+  attribute_type: AttributeType;
+  config?: AttributeConfig | null;
+  default_value?: unknown | null;
+  description?: string | null;
+  is_default_value_enabled?: boolean;
+  is_multiselect?: boolean;
+  is_required?: boolean;
+  is_unique?: boolean;
+  slug: string;
+  sort_order?: number;
+  title: string;
+}
+
+/** 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;
+}
+
+/** Valid attribute types for the Custom Objects type system. */
+export type AttributeType = "text" | "number" | "currency" | "date" | "timestamp" | "checkbox" | "select" | "status" | "email_address" | "phone_number" | "domain" | "location" | "personal_name" | "record_reference" | "rating" | "actor_reference";
+
+export interface AttributeUpdateRequest {
+  config?: AttributeConfig | null;
+  default_value?: unknown | null;
+  description?: string | null;
+  is_archived?: boolean | null;
+  is_default_value_enabled?: boolean | null;
+  is_multiselect?: boolean | null;
+  is_required?: boolean | null;
+  is_unique?: boolean | null;
+  sort_order?: number | null;
+  title?: string | null;
+}
+
+export interface ObjectCreateRequest {
+  description?: string | null;
+  icon?: ("box" | "briefcase" | "building" | "calendar" | "flag" | "folder" | "globe" | "heart" | "layers" | "package" | "target" | "users") | null;
+  plural_noun: string;
+  singular_noun: string;
+  slug: 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 ObjectUpdateRequest {
+  description?: string | null;
+  display_attribute_slug?: string | null;
+  icon?: ("box" | "briefcase" | "building" | "calendar" | "flag" | "folder" | "globe" | "heart" | "layers" | "package" | "target" | "users") | null;
+  is_archived?: boolean | null;
+  plural_noun?: string | null;
+  singular_noun?: string | 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;
+}
+
+/**
+ * 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>;
+}
+
+export interface RecordUpsertRequest {
+  expected_revision?: number | null;
+  /** Active single-value unique attribute. Its nonempty value must be supplied in values. */
+  matching_attribute: string;
+  /** 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>;
+}