@fayz-ai/core 0.9.0 → 0.11.0

package/dist/integrations/events.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Whether a subscription pattern covers an event key. One implementation on
+ * purpose: the ingress, the settings UI and the docs' examples all have to agree
+ * on what `blog.post.*` means, and a second matcher is a silent divergence.
+ */
+export declare function eventKeyMatches(pattern: string, key: string): boolean;
+//# sourceMappingURL=events.d.ts.map

package/dist/integrations/events.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"events.d.ts","sourceRoot":"","sources":["../../src/integrations/events.ts"],"names":[],"mappings":"AAGA;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,MAAM,GAAG,OAAO,CAKrE"}

package/dist/integrations/index.d.ts

@@ -1,7 +1,29 @@
 import type * as React from 'react';
+import type { ConnectorPermission } from './permissions';
+import type { RequestFailureMode } from './request';
+import type { Completeness, Cursor, RateLimitBudget } from './runtime';
+import type { ConnectorSetting, ConnectorSettingValue } from './settings';
+export { permissionActions, isDataPermission, isEventPermission, grants, connectorPermissions, connectorEntities, connectorSubscribesTo, connectorSubscribes, permissionsWrite, hasSensitivePermission, sortedPermissions, groupedPermissions, connectorGrantScopes, } from './permissions';
+export type { ConnectorPermission, ConnectorPermissionAction, ConnectorResourceKind, PermissionBearing, } from './permissions';
+export { eventKeyMatches } from './events';
+export { CONNECTOR_RUNTIME_TOKEN_HEADER, ConnectorRuntimeTokenUnavailableError, connectorRuntimeToken, getConnectorRuntimeTokenSource, setConnectorRuntimeTokenSource, } from './runtime-token';
+export type { ConnectorRuntimeTokenRequest, ConnectorRuntimeTokenSource } from './runtime-token';
+export { createConnectionStore, listConnections, connectionKey, connectionStatus, connectionSettings, connectionRuns, assertSettingsAllowed, ConnectionSettingsError, CONNECTIONS_TABLE, SYNC_RUNS_TABLE, } from './store';
+export type { ConnectionStore, ConnectionStoreOptions, ConnectionSaveInput, ConnectionBackedStatus, ConnectionSettingsIO, ConnectionRunsIO, ListConnectionsOptions, } from './store';
+export { connectorSettings, isSettingSet, missingRequiredSettings, settingsStatus, setupStatusDetail, } from './settings';
+export type { ConnectorSetting, ConnectorSettingType, ConnectorSettingOption, ConnectorSettingValue, SettingsReadiness, } from './settings';
+export { runRequest, runEffect, requestPlaneSpec, hasRequestPlane, buyerIdempotencyKey, createRpcEffectLedger, RequestBlockedError, RequestPlaneError, } from './request';
+export type { RequestFailureMode, DegradeReason, RequestOutcome, RequestAttempt, ResolvedRequestPlane, EffectLedger, EffectClaim, EffectClaimInput, EffectOutcome, EffectStatus, } from './request';
+export { ConnectorHttpError, RateLimitExceededError, parseRetryAfter, backoffDelay, classify, statusNeedsBody, fetchWithRetry, isExpiring, paginate, createRateLimiter, sliceWindow, advanceWindow, serializeCursor, reconcileMirror, cursorCompleteness, } from './runtime';
+export type { Cursor, Completeness, Verdict, AttemptOutcome, ClassifyOptions, BackoffOptions, FetchWithRetryOptions, MinimalResponse, PageResult, PaginateOptions, PaginateResult, RateLimitBudget, RateLimiter, RateLimiterOptions, MirrorRecord, ReconcileInput, ReconcileResult, } from './runtime';
 /** How a connector authenticates to its provider. */
 export type IntegrationAuthKind = 'oauth' | 'api-key' | 'mtls';
-export type ConnectorPlane = 'agentic' | 'sync';
+export declare const CONNECTOR_CATEGORIES: readonly ["database", "payments", "banking", "erp", "logistics", "marketplace", "ecommerce", "crm", "courses", "scheduling", "messaging", "analytics", "local", "ai", "automation"];
+/** A shelf in the connector catalogue. See {@link CONNECTOR_CATEGORIES}. */
+export type ConnectorCategory = (typeof CONNECTOR_CATEGORIES)[number];
+/** Whether a string is a category the catalogue knows. */
+export declare function isConnectorCategory(value: unknown): value is ConnectorCategory;
+export type ConnectorPlane = 'agentic' | 'sync' | 'request';
 /** Which side reaches for the other, from this app's point of view. */
 export type ConnectorDirection = 'inbound' | 'outbound';
 /** A tool the assistant gains once a connector is resolved on the agentic plane. */
@@ -20,32 +42,84 @@ export interface ConnectorCapability {
     direction: SyncDirection;
     triggers: SyncTrigger[];
 }
-/** The state of a tenant's connection to a provider (one row in a *_integrations table). */
+/**
+ * One row of `public.plg_connections` (migration 029) — a tenant's connection to
+ * ONE account at one provider. Two accounts are two rows, separated by
+ * `instanceKey`; two resources inside one account are two streams of one row.
+ *
+ * There is no credential field because the table has no credential column.
+ */
 export interface ConnectionConfig {
-    /** Provider key, e.g. 'google', 'plugbank'. */
-    provider: string;
-    /** Whether the connection is active and should sync. */
+    id?: string;
+    tenantId?: string;
+    /** Connector id, e.g. 'google-calendar', 'plugbank'. */
+    connectorId: string;
+    /** Which account at the provider. `''` for the connectors that only ever have one. */
+    instanceKey: string;
+    displayName?: string | null;
+    /** The tenant's switch. */
     active: boolean;
-    /** Opaque, provider-specific config (calendar id, account id, cursor, …). Never secrets. */
-    settings?: Record<string, unknown>;
-    /** Last successful sync, ISO timestamp. */
-    lastSyncAt?: string;
+    /** Health, observed server-side — not a mirror of `active`. */
+    status: ConnectionStatusValue;
+    statusDetail?: string | null;
+    /** Provider-specific config, restricted to the connector's declared field keys. Never secrets. */
+    settings: Record<string, unknown>;
+    /** The provider's own id for the account — how an inbound webhook finds the tenant. */
+    providerAccountKey?: string | null;
+    /** Resume state keyed BY STREAM: Google keeps a syncToken per calendar, not per connection. */
+    cursors: Record<string, Cursor>;
+    lastSyncAt?: string | null;
+    createdAt?: string;
+    updatedAt?: string;
 }
-/** Audit record of one sync execution (generalizes *_sync_log / *_sync_runs). */
+/** Server-observed health of a connection (`plg_connections.status`). */
+export type ConnectionStatusValue = 'pending' | 'connected' | 'error' | 'revoked';
+/** One row of `public.plg_sync_runs` (migration 029) — one execution of the sync plane. */
 export interface SyncRun {
     id?: string;
-    provider: string;
-    direction: SyncDirection;
-    trigger: SyncTrigger;
+    tenantId?: string;
+    /** Which connection ran. Without it two bank accounts share one history. */
+    connectionId: string;
+    connectorId: string;
+    direction: ConnectorDirection;
+    /** `trigger` is a reserved word in Postgres; the column is `trigger_kind`. */
+    triggerKind: SyncTrigger;
+    status: 'running' | 'success' | 'partial' | 'error';
+    /** Which resource inside the account this run touched. */
+    stream?: string | null;
+    fetched?: number;
+    written?: number;
+    /** Counters that are the connector's own: duplicates, discovered, period_from/to. */
+    stats?: Record<string, unknown>;
+    /** The cursor this run advanced to, serialised. */
+    cursor?: string | null;
+    /** Ties an outbound push to the inbound echo it will provoke. */
+    correlationId?: string | null;
+    /**
+     * What the run has to SAY, on any status (migration 031). `error` is what went
+     * WRONG; a successful run with something to report used to smuggle it through
+     * `stats.message`, which is the ad-hoc convention the generic table exists to
+     * prevent.
+     */
+    message?: string | null;
+    error?: string | null;
+    startedAt?: string;
+    finishedAt?: string | null;
+}
+/**
+ * What a connector's sync returns. Distinct from {@link SyncRun}: `completeness`
+ * is not a column, it is the verdict the engine needs BEFORE it decides whether
+ * records missing from this result may be cancelled locally.
+ */
+export interface SyncResult {
     status: 'success' | 'partial' | 'error';
-    /** Items pulled/pushed and how many were written. */
+    completeness: Completeness;
     fetched?: number;
     written?: number;
-    /** Pagination/incremental cursor advanced by this run. */
-    cursor?: string;
+    /** Advanced cursor, to be written back under its stream key. */
+    cursor?: Cursor;
+    stats?: Record<string, unknown>;
     error?: string;
-    startedAt?: string;
-    finishedAt?: string;
 }
 export interface TestConnectionResult {
     ok: boolean;
@@ -67,35 +141,194 @@ export interface Connector {
     capabilities: ConnectorCapability[];
     /** Validate the stored credentials/config without syncing. */
     testConnection?(config: ConnectionConfig): Promise<TestConnectionResult>;
-    /** Run a sync for the given direction; returns the audit record. */
+    /** Run a sync for the given direction; the caller files the run server-side. */
     sync?(input: {
         config: ConnectionConfig;
         direction: SyncDirection;
         trigger: SyncTrigger;
-    }): Promise<SyncRun>;
+    }): Promise<SyncResult>;
 }
-/** A credential input the unified setup form renders for an api-key/mtls connector. */
+/**
+ * An input the connect step renders — **what authorizes the connection**, and
+ * nothing else.
+ *
+ * The rule, in one line: if the connection cannot be established without it, it
+ * is a field; if it changes how a live connection behaves, it is a
+ * {@link ConnectorSetting}. An API key is a field. The account identifier the
+ * key is scoped to is a field. Which payment methods the store accepts, or which
+ * postcode it ships from, is not — see ./settings.ts.
+ *
+ * `type: 'password'` is the marker the credential seam reads: a password field
+ * never reaches connector-author code and never reaches
+ * `plg_connections.settings`.
+ */
 export interface ConnectorField {
     key: string;
     label: string;
     type: 'text' | 'password';
     placeholder?: string;
+    /**
+     * Route this to the credential sink even though it is not masked.
+     *
+     * For the half of a credential PAIR that is not itself confidential — AppMax
+     * issues `client_id` alongside `client_secret`, and the id is useless to
+     * anyone without the secret. Masking it would only stop the merchant checking
+     * they pasted the right one; letting it fall through to the connector's own
+     * `saveConnection` would split one credential across two stores, which is
+     * how half of it ends up in a pool table.
+     */
+    secret?: boolean;
+}
+/**
+ * A door the merchant goes through AT THE PROVIDER before the connect step can
+ * be finished — and the reason the hub does not have to know which provider.
+ *
+ * Not every partner hands back a code on a redirect. AppMax issues the
+ * `client_id`/`client_secret` pair when the merchant INSTALLS our app inside
+ * their own AppMax admin ("chaves emitidas na instalação do app"), and only
+ * then shows them something to copy. An OAuth button there would be a button
+ * that lies: nothing comes back, and pressing it could never connect anything.
+ * What is true is a two-step gesture — go install it there, come back and paste
+ * what it showed you — so the gesture is declared and the panel renders it
+ * above {@link ConnectorDefinition.fields}.
+ *
+ * Declared and not hardcoded in the UI because the address is a fact about
+ * THIS app's registration at that provider, which the hub cannot know and a
+ * second connector with the same gesture will spell differently.
+ *
+ * An OAuth connector declares none: consent is the install.
+ */
+export interface ConnectorProviderInstall {
+    /** Where the merchant installs this app at the provider. Opened in a new tab. */
+    url: string;
+}
+/**
+ * What the hub knows about who is connecting, handed to
+ * {@link ConnectorDefinition.startOAuth}.
+ *
+ * `tenantId` is a SELECTOR and never an assertion: the platform proves
+ * membership from the token it was called with and refuses anything outside it,
+ * so naming an organization here narrows which of the caller's own orgs the
+ * consent is for and can never widen it. Without it a merchant who belongs to
+ * two organizations cannot be told apart from one who belongs to neither.
+ */
+export interface ConnectorConnectContext {
+    tenantId?: string;
+}
+/**
+ * An automation the connector owns rather than the tenant.
+ *
+ * "New sale → send it to Bling" is not a preference someone chose; it is what
+ * the integration IS. So it appears in the automations screen only while the
+ * connection is live, and the screen must not offer to delete it — a deleted
+ * row would leave the integration connected and silently half-wired, which
+ * reads as "Bling stopped working" weeks later. Disconnecting is the way out.
+ */
+export interface ConnectorManagedAutomation {
+    /** Domain event that fires it. Must be covered by `subscribesTo`. */
+    eventKey: string;
+    /** What the tenant is told it does ("Send the sale to Bling"). */
+    label: string;
+    /** Whether the tenant may switch it off and stay connected. Default false. */
+    optional?: boolean;
+}
+/** One call site that invokes a connector, and what happens there. */
+export interface ConnectorInvocation {
+    /**
+     * Stable call-site key, `<plugin>.<surface>.<verb>` —
+     * `shop.checkout.shipping_quote`. Not an event key: nothing publishes it, it
+     * names a place in the code, and it is what a support conversation and a trace
+     * will call the same call.
+     */
+    key: string;
+    /** What the tenant is told happens there ("O cliente pede as opções de frete"). */
+    label: string;
+    /**
+     * Which plane carries the call. Default `'request'` — the buyer is waiting.
+     * `'sync'` for the effects a request leads to (capture the payment, buy the
+     * label), which DO file a run.
+     */
+    plane?: Extract<ConnectorPlane, 'request' | 'sync'>;
+    /** Sync moments only: what fires it, in `plg_sync_runs.trigger_kind`'s words. */
+    trigger?: SyncTrigger;
+    /**
+     * Which declared resources this call reaches — `permissions[].resource` names.
+     *
+     * The half of "quando ele age" that was missing: the section said *when* a
+     * connector is called and never *what it gets at*. Naming the resource rather
+     * than restating the access is what keeps the two from disagreeing — a moment
+     * cannot reach something the connector did not ask for, and the contract check
+     * enforces exactly that.
+     */
+    touches?: string[];
+}
+/** The plane a moment runs on when it does not say. */
+export declare function invocationPlane(moment: ConnectorInvocation): Extract<ConnectorPlane, 'request' | 'sync'>;
+/**
+ * The two entries a first load has when the provider's catalogue is big enough
+ * that pulling it in line is not an option.
+ *
+ * Keeping them apart is forced by the budget, not by taste: at 3 req/s a
+ * ten-thousand-product catalogue is nearly an hour, and a connect screen that
+ * waits for it is a connect screen nobody finishes.
+ */
+export interface ConnectorFirstLoad {
+    /** How many records the fast phase pulls before answering. */
+    sampleSize: number;
+    /** Pages the fast phase may spend. A sample that pages forever is a backfill. */
+    samplePages?: number;
+    /** Which stream the phases walk (`'products'`, `'orders'`). */
+    stream: string;
 }
 export interface ConnectorStatus {
     connected: boolean;
     detail?: string;
+    /**
+     * What is wrong with a live connection, in sentences a merchant can act on.
+     *
+     * `detail` is one line and is what a LIST row has room for; a connection can
+     * be unwell in more than one way at once (the watch expired AND the timezone
+     * drifted), and a connector that had more to say used to say it in its own
+     * panel — which put status on the settings tab and left `detail` repeating the
+     * first item. Declaring both is what lets the surface render the list once and
+     * fall back to `detail` when there is nothing to enumerate.
+     */
+    issues?: string[];
     /** Which plane the live connection is running on (when connected). */
     plane?: ConnectorPlane;
+    /**
+     * Connected, and unable to do its job until a required-to-operate setting is
+     * chosen — `plg_connections.status = 'pending'`.
+     *
+     * Not a third kind of "connected": the connection is real, the authorization
+     * happened, and nothing about it needs redoing. What is missing is
+     * configuration, which is why it is reported here rather than by pretending
+     * the connect step failed. See {@link settingsStatus}.
+     */
+    needsSetup?: boolean;
+    /** Which setting keys are missing. Keys only — never what the tenant typed. */
+    missingSettings?: string[];
 }
 /**
  * UI-facing connector descriptor. Built on the data-plane `Connector` concept
  * (`pluginId` → `hostPluginId`), plus the control-plane hooks the unified
  * Integrations hub calls. Lives in core so `PluginManifest.connectors` can type
- * it; the rendering hub lives in `@fayz-ai/saas`.
+ * it; the rendering hub lives in `@fayz-ai/admin`.
  */
 export interface ConnectorDefinition {
     /** Stable connector id, e.g. 'google-calendar', 'plugbank'. */
     id: string;
+    /**
+     * The platform catalogue slug this connector IS, when it differs from `id`.
+     *
+     * `id` names the implementation and `slug` names the provider, and they are
+     * only usually the same word: `plugbank` is the catalogue's `tecnospeed`.
+     * The tie matters twice — it is what lends
+     * an installed connector the catalogue's localized copy and brand mark, and
+     * what tells a slug a module declared in {@link PluginManifest.integrations}
+     * apart from one still to be built.
+     */
+    catalogSlug?: string;
     /** The plugin this connector extends, e.g. 'financial', 'agenda'. */
     hostPluginId: string;
     name: string;
@@ -111,33 +344,304 @@ export interface ConnectorDefinition {
     authKind: IntegrationAuthKind;
     /** Planes this connector can be honoured on. Default: `['sync']`. */
     planes?: ConnectorPlane[];
+    /**
+     * Request plane only, and required there: how long the buyer may wait before
+     * `onFailure` applies. No default — see {@link requestPlaneSpec}.
+     */
+    latencyBudgetMs?: number;
+    /**
+     * Request plane only, and required there. `'degrade'` serves a worse answer
+     * and the sale continues; `'block'` refuses the step and the buyer is told
+     * why. A field, not a decision re-taken in every screen that calls it.
+     */
+    onFailure?: RequestFailureMode;
     /** Default `'outbound'` — this app reaching a provider. */
     direction?: ConnectorDirection;
     /** What the assistant gains on the agentic plane — shown before connecting. */
     agentTools?: ConnectorAgentTool[];
-    /** Canonical entities this connector touches ('booking', 'movement'). */
+    /**
+     * **What this connector needs access to, and why** — the one declaration the
+     * consent view, "quando ele age" and (eventually) the minted credential all
+     * read. See ./permissions.ts.
+     *
+     * It SUBSUMES {@link entities} and {@link subscribesTo}: declare permissions
+     * and both are derived ({@link connectorEntities}, {@link connectorSubscribesTo}).
+     * Declaring a permission and a contradicting legacy field fails the contract
+     * check rather than being merged — a connector that says it writes `booking`
+     * in one field and never mentions `booking` in the other has a bug, and
+     * picking a winner would hide it.
+     */
+    permissions?: ConnectorPermission[];
+    /**
+     * Canonical entities this connector touches ('booking', 'movement').
+     *
+     * Superseded by {@link permissions}, which says read or write rather than only
+     * the name. Still read for connectors built against an older core; when both
+     * are present they must name the same set. Read it through
+     * {@link connectorEntities}, never off the field.
+     */
     entities?: string[];
-    /** Catalog category ('scheduling', 'payments', …) — matches the Fayz catalog. */
-    category?: string;
+    /**
+     * The catalogue shelf, from the closed vocabulary in
+     * {@link CONNECTOR_CATEGORIES}. Typed rather than free-form because the badge
+     * that renders it is keyed by this exact string: an unlisted one renders no
+     * badge at all, which is invisible in review and invisible in the screenshot.
+     */
+    category?: ConnectorCategory;
+    /**
+     * The provider's call budget for ONE account, declared rather than discovered.
+     *
+     * The scheduler owns the clock ({@link createRateLimiter}); a `sleep` inside a
+     * connector's fetch helper cannot express a daily ceiling and cannot be shared
+     * between two streams pulling at the same time. Declaring it is also what
+     * makes "never one request per product" a checkable statement instead of a
+     * habit — see {@link firstLoad}.
+     */
+    rateLimit?: RateLimitBudget;
+    /**
+     * How the first load enters, when the catalogue is too large to fetch in line.
+     *
+     * Two phases, because they answer different questions: `sample` returns in
+     * seconds and is what a briefing or a generated storefront is designed
+     * against; `backfill` runs in the background against the budget and is what
+     * makes the mirror complete. Absent = the first load is just a sync.
+     */
+    firstLoad?: ConnectorFirstLoad;
     /** Provider documentation, linked from the connector's detail. */
     docsUrl?: string;
-    /** Declarative credentials — the unified form renders these (api-key / mtls). */
+    /**
+     * What AUTHORIZES the connection — the connect step renders exactly these and
+     * nothing more (api-key / mtls). An OAuth connector declares none: consent is
+     * the whole form.
+     *
+     * A connector whose credential lives in the Fayz platform declares none
+     * either, and the connect step says so rather than drawing an empty grid.
+     */
     fields?: ConnectorField[];
+    /**
+     * The provider-side install the merchant must do first, when there is one.
+     * Rendered above `fields`. See {@link ConnectorProviderInstall}.
+     */
+    providerInstall?: ConnectorProviderInstall;
+    /**
+     * How the live connection BEHAVES — asked for only after it exists.
+     *
+     * The split is the point. Everything here changes with the season and none of
+     * it belongs in front of someone who has not connected yet; see ./settings.ts.
+     * Declaring a setting also allow-lists its key for
+     * `plg_connections.settings`, so a connector needs it in one place, not two.
+     */
+    settings?: ConnectorSetting[];
+    /** Current values for the settings form. Required whenever `settings` is declared. */
+    getSettings?(): Promise<Record<string, unknown>>;
+    /** Persist a settings patch — merged by key, never replacing the jsonb. */
+    saveSettings?(values: Record<string, ConnectorSettingValue>): Promise<void>;
+    /**
+     * The moments this connector is CALLED at — the request plane's answer to
+     * "acionado quando?". See {@link ConnectorInvocation}.
+     */
+    invokedAt?: ConnectorInvocation[];
+    /**
+     * Domain-event keys this connector reacts to — exact keys or `*`-suffixed
+     * prefixes (`agenda.booking_created`, `blog.post.*`). The ingress reads it to
+     * decide which facts are worth waking the connector for; without it every
+     * connector would have to be handed every event and filter it itself.
+     *
+     * Superseded by a `kind: 'event'` {@link permissions} entry carrying `listen`,
+     * which says the same thing plus why. Same agreement rule as {@link entities}.
+     * Read it through {@link connectorSubscribesTo}, never off the field.
+     */
+    subscribesTo?: string[];
+    /** Automations this connector owns. See {@link ConnectorManagedAutomation}. */
+    managedAutomations?: ConnectorManagedAutomation[];
     /** Current connection state for the status badge. */
     getStatus(): Promise<ConnectorStatus>;
+    /**
+     * The same answer as {@link getStatus}, derived from a `plg_connections` row a
+     * caller already holds.
+     *
+     * Declaring it is what lets a list of N connectors resolve in ONE batched read
+     * (`listConnections`) instead of N `getStatus()` round trips — the connectors
+     * screen used to issue one request per row. Pure by contract: it is handed a
+     * row, it must not fetch.
+     *
+     * Absent means "my truth is not in that table" (Stripe Connect derives from
+     * the provider), and the list falls back to calling `getStatus()`. Use
+     * {@link connectionStatus} to write both from one function.
+     */
+    statusFromConnection?(connection: ConnectionConfig | null): ConnectorStatus;
+    /** Which account at the provider `statusFromConnection` reads. Default `''`. */
+    instanceKey?: string;
     /** Validate credentials without persisting (api-key / mtls). */
     testConnection?(values: Record<string, string>): Promise<TestConnectionResult>;
     /** Persist the connection (api-key / mtls). */
     saveConnection?(values: Record<string, string>): Promise<void>;
-    /** Begin an OAuth connect flow — returns the consent URL to redirect to. */
-    startOAuth?(redirectTo?: string): Promise<string>;
+    /**
+     * Begin an OAuth connect flow — returns the consent URL to redirect to.
+     *
+     * `context` is optional so a connector written against an older core keeps
+     * compiling; the hub always passes it. See {@link ConnectorConnectContext}.
+     */
+    startOAuth?(redirectTo?: string, context?: ConnectorConnectContext): Promise<string>;
     /** Tear down the connection. */
     disconnect?(): Promise<void>;
+    /**
+     * What unplugging costs, when the answer is not obvious.
+     *
+     * A mirror that freezes is not a catalogue that is deleted, and a merchant
+     * who cannot tell the two apart never presses the button. Rendered beside
+     * Desconectar, which is the only place the question is ever asked.
+     */
+    disconnectNote?: string;
+    /**
+     * When this connector syncs, in the merchant's words.
+     *
+     * The first question anyone has after connecting, and one the screen could
+     * not answer: the cadence lives in `plg_connector_schedules`, the on-write
+     * wake in a database trigger, the manual run in a button — three places, none
+     * of them a sentence. Rendered on Visão geral.
+     */
+    howItSyncs?: string[];
     /** Move an existing connection between planes (only when `planes` has both). */
     setPlane?(plane: ConnectorPlane): Promise<void>;
-    /** Optional connector-specific UI below the connect panel (import / sync / history). */
+    /**
+     * What this connection has DONE — newest first.
+     *
+     * The surface renders one history for every connector, so a connector
+     * declares where its runs are and nothing about how they look. Store-backed
+     * connectors get it from {@link connectionRuns}; a connector whose runs live
+     * in its own table maps them onto {@link SyncRun} here, which is the only
+     * shape the view knows.
+     *
+     * Absent means "I keep no history", and the surface offers no history tab —
+     * never an empty one, which would read as "nothing ever ran".
+     */
+    listRuns?(options?: {
+        limit?: number;
+    }): Promise<SyncRun[]>;
+    /**
+     * The connector's own actions that PRODUCE a run — sync now, import a
+     * statement, pull events from a date.
+     *
+     * Deliberately separate from {@link ExtraPanel}: an import is something
+     * somebody does once, and it was rendered beside a settings form, which is
+     * where the two got confused. Rendered above the history, because the history
+     * is where its effect shows up.
+     *
+     * `onRan` reloads that history — call it after the action lands.
+     */
+    RunActions?: React.ComponentType<{
+        onRan?: () => void;
+    }>;
+    /**
+     * The same thing as {@link RunActions}, DECLARED instead of drawn.
+     *
+     * What differs between two connectors is the sentence on the button and the
+     * call behind it. Spinner, toast, reloading the history, confirming a write at
+     * the provider — the surface owns all of it, or two integrations end up
+     * feeling like two products.
+     *
+     * Both seams render, so a connector can migrate one action at a time.
+     */
+    syncActions?: ConnectorSyncAction[];
+    /**
+     * Record by record: what reached the provider, what is queued, what was
+     * refused. The seam the automations screen reads — a managed automation could
+     * only show that the fact FIRED, never that anything arrived.
+     */
+    listDeliveries?(options?: {
+        eventKey?: string;
+        limit?: number;
+    }): Promise<ConnectorDelivery[]>;
+    /**
+     * The connector's own CONFIGURATION UI, rendered on the Settings tab.
+     *
+     * Configuration only: which Google calendar maps to which professional, which
+     * warehouse a stream belongs to. Status belongs in {@link ConnectorStatus},
+     * history in {@link listRuns}, and a one-off action in {@link RunActions} —
+     * this panel used to hold all four at once.
+     */
     ExtraPanel?: React.ComponentType;
 }
+/**
+ * One RECORD's journey to the provider — "cadastrei aqui, foi?".
+ *
+ * A {@link SyncRun} says "12 of 20 filed", which is the number that does not
+ * help the person holding order 1042 in their hand.
+ */
+export interface ConnectorDelivery {
+    /** The record, as the merchant would name it: "Pedido 1042", "Costela defumada". */
+    subject: string;
+    /** This app's id for it, when a screen wants to link back to the record. */
+    subjectId?: string;
+    /** `pending` is a real answer: queued, not yet sent — what the merchant sees
+     *  in the fifteen minutes between a sale and the clock. */
+    status: 'delivered' | 'pending' | 'failed';
+    /** Why it is pending or failed, in the merchant's language. */
+    detail?: string;
+    /** The id or number it got at the provider. The one thing checkable on both screens. */
+    externalId?: string;
+    /** When it was delivered, or when the record was created if it was not. */
+    at?: string;
+}
+/** What a run actually did. `partial` and `error` are toasted as such. */
+export interface ConnectorSyncOutcome {
+    message: string;
+    status?: 'success' | 'partial' | 'error';
+}
+/** One thing a merchant can make a connection DO. Declared rather than drawn —
+ *  see {@link ConnectorDefinition.syncActions}. */
+export interface ConnectorSyncAction {
+    /** Stable, for React keys and for telling two actions apart in a test. */
+    key: string;
+    /** The button. A verb, in the merchant's language: "Trazer catálogo do Bling". */
+    label: string;
+    /** Which way the data moves. Outbound is a write the merchant cannot undo
+     *  from this screen, which is what `confirm` is for. */
+    direction: 'inbound' | 'outbound';
+    /** One line under the label, when the label alone cannot carry it. */
+    description?: string;
+    /**
+     * The action somebody came here to press — the one that is right on an
+     * ordinary day. At most one. The rest fold under "Outras ações": five equal
+     * buttons is a menu the reader has to grade themselves.
+     */
+    primary?: boolean;
+    /** Ask first. Only for what cannot be taken back. */
+    confirm?: {
+        title: string;
+        body: string;
+        cta: string;
+    };
+    /**
+     * Do it. What it returns becomes the toast — use the run's own sentence, so
+     * the merchant reads the same words here and in the history below.
+     *
+     * Return a {@link ConnectorSyncOutcome} when the run can partly fail: a push
+     * that filed 0 of 9 answers 200 with a sentence, and a surface that reads only
+     * "it did not throw" celebrates it. The verdict is already computed where the
+     * work happened; this is how it reaches the screen.
+     */
+    run(): Promise<string | ConnectorSyncOutcome | void>;
+    /**
+     * How many records are still waiting for this action.
+     *
+     * `0` means there is nothing left to send, and the surface says so — a check
+     * and a spent button, not a live control that would file nothing. A push whose
+     * queue is an absence can always answer this; a pull cannot know what changed
+     * at the provider, so it declares nothing and stays enabled.
+     */
+    pending?(): Promise<number | null> | number | null;
+    /** Whether to offer it at all. Hidden, not disabled: a greyed button reads as
+     *  something the reader failed to do. Absent means always. */
+    available?(): Promise<boolean> | boolean;
+    /** A screen of its own, for an action that needs choices first. Replaces the
+     *  row while open; call `onRan` when something actually happened. */
+    Component?: React.ComponentType<{
+        onClose(): void;
+        onRan?(): void;
+    }>;
+}
 /** Planes a connector supports — the contract's default is the sync pipeline. */
 export declare function connectorPlanes(def: Pick<ConnectorDefinition, 'planes'>): ConnectorPlane[];
 /**