@startsimpli/integrations 0.1.0 → 0.1.3

package/src/components/pages/types.ts

@@ -0,0 +1,176 @@
+/**
+ * The STRUCTURAL contract `ConnectionsPage` is handed.
+ *
+ * Deliberately re-declared here rather than imported from `@startsimpli/api`:
+ * the composer takes an *injected* api the same way `TeamSettingsPage` does, so
+ * it must depend on a SHAPE, not on a client. A test hands it an object
+ * literal; an app hands it `apiClient.foundry`, whose method names are these on
+ * purpose. Neither one needs a React context or an app-local provider.
+ */
+
+export interface ConnectorFieldSpec {
+  key: string;
+  label: string;
+  /**
+   * The server's own vocabulary — `text`, `url`, `select`, `secret`, ... A type
+   * this build has never heard of degrades to a text input rather than blanking
+   * the form: the catalog is DATA and will outrun the deployed bundle.
+   */
+  type?: string;
+  /**
+   * Server-enforced companion of `type: "secret"` — a connector cannot override
+   * it. Either one masks the field; `secret` is accepted too for callers that
+   * hand-build a schema.
+   */
+  write_only?: boolean;
+  secret?: boolean;
+  mask?: string;
+  required?: boolean;
+  help?: string;
+  placeholder?: string;
+  options?: Array<{ value: string; label: string }> | null;
+  default?: string | null;
+  pattern?: string | null;
+  docs_url?: string;
+}
+
+/**
+ * A schema as the catalog SHIPS it: `{version, fields[]}`, array order = render
+ * order. Accepting a bare array too is not sloppiness — a caller composing a
+ * schema by hand should not have to know the envelope, and the envelope is
+ * exactly the thing that may gain a version this build does not recognise.
+ */
+export interface ConnectorSchema {
+  version?: number;
+  fields?: ConnectorFieldSpec[];
+}
+
+export type ConnectorSchemaLike = ConnectorSchema | ConnectorFieldSpec[] | null | undefined;
+
+export interface ConnectorCatalogEntry {
+  key: string;
+  name: string;
+  description: string;
+  logo_url: string;
+  docs_url: string;
+  capabilities: string[];
+  auth_mode: string;
+  credential_schema: ConnectorSchemaLike;
+  config_schema: ConnectorSchemaLike;
+  record_types: string[];
+  supports_webhooks: boolean;
+  /** A row whose class will not import says so here rather than vanishing. */
+  availability: { available: boolean; reason: string };
+}
+
+export type ConnectionStatus = 'connected' | 'needs_reauth' | 'error' | 'disabled';
+
+export interface Connection {
+  id: string;
+  public_id: string;
+  name: string;
+  connector_key: string;
+  connector_name: string;
+  external_account_id: string;
+  account_label: string;
+  capabilities_enabled: string[];
+  config: Record<string, unknown>;
+  status: ConnectionStatus;
+  health: string;
+  auth_mode: string;
+  check_error?: string;
+  last_checked_at?: string | null;
+}
+
+/** What to RENDER, never what to allow. The server refuses on its own. */
+export interface ConnectionPermissions {
+  view: boolean;
+  manage: boolean;
+  issue_tokens: boolean;
+}
+
+export interface ConnectionChoice {
+  id: string;
+  label: string;
+  kind: string;
+  selectable: boolean;
+  reason: string;
+  remediation: string;
+  hidden_by_default: boolean;
+  detail: Record<string, unknown>;
+}
+
+export interface ConnectionChoicePage {
+  results: ConnectionChoice[];
+  kind: string;
+  cursor: string | null;
+  has_more: boolean;
+}
+
+export interface ConnectionTarget {
+  id: string;
+  name: string;
+  provider_key: string;
+  entity_type: string;
+  is_active: boolean;
+  destination_config: Record<string, unknown>;
+  verified: boolean;
+}
+
+export interface ConnectorAction {
+  name: string;
+  label: string;
+  input_schema: Record<string, unknown>;
+}
+
+export interface ConnectionInvokeResult {
+  ok: boolean;
+  action: string;
+  destination_id: string;
+  run_id: string;
+  run_status: string;
+  external_ref: string | null;
+  output: Record<string, unknown>;
+  error: string;
+}
+
+export interface ConnectionRun {
+  id: string;
+  kind: string;
+  object_id: string;
+  name: string;
+  status: string;
+  run_type: string;
+  occurred_at: string;
+  error_message: string;
+}
+
+export interface ConnectionsApi {
+  connectorCatalog(slug: string): Promise<{ results: ConnectorCatalogEntry[] }>;
+  connections(slug: string): Promise<{
+    results: Connection[];
+    permissions: ConnectionPermissions;
+  }>;
+  connect(slug: string, input: {
+    connector_key: string;
+    name?: string;
+    credentials?: Record<string, unknown>;
+    config?: Record<string, unknown>;
+  }): Promise<Connection>;
+  checkConnection(slug: string, id: string): Promise<{
+    ok: boolean; account_label: string; detail: string;
+  }>;
+  disconnect(slug: string, id: string): Promise<void>;
+  connectionChoices(slug: string, id: string, params?: {
+    kind?: string; cursor?: string;
+  }): Promise<ConnectionChoicePage>;
+  wireTarget(slug: string, id: string, input: {
+    choice_id: string; name?: string; options?: Record<string, unknown>;
+  }): Promise<ConnectionTarget>;
+  confirmTarget(slug: string, id: string, destinationId: string): Promise<ConnectionTarget>;
+  connectionActions(slug: string, id: string): Promise<{ results: ConnectorAction[] }>;
+  invokeConnectionAction(slug: string, id: string, action: string, input: {
+    destination_id: string; record_type?: string; records?: unknown[];
+  }): Promise<ConnectionInvokeResult>;
+  connectionRuns(slug: string, id: string): Promise<{ results: ConnectionRun[] }>;
+}