patchwork-os 0.2.0-beta.1 → 0.2.0-beta.10.canary.100

package/dist/connectors/salesforce.d.ts

@@ -0,0 +1,136 @@
+/**
+ * Salesforce OAuth 2.0 connector.
+ *
+ * Handles:
+ *   GET    /connections/salesforce/auth      — redirect to Salesforce login consent
+ *   GET    /connections/salesforce/callback  — exchange code → tokens (captures instance_url)
+ *   POST   /connections/salesforce/test      — health check against /services/data/<v>/
+ *   DELETE /connections/salesforce           — revoke + delete stored token
+ *
+ * Multi-tenant nuance:
+ *   Salesforce is multi-tenant. Each org has a unique `https://your-org.my.salesforce.com`
+ *   base URL returned in the token response as `instance_url`. This value MUST be
+ *   persisted in the tokens file — every subsequent API call uses it as the base URL.
+ *   The login host (login.salesforce.com vs test.salesforce.com) is configurable via
+ *   SALESFORCE_LOGIN_HOST so sandbox orgs can flip the front-door host without code
+ *   changes; the instance_url returned from the token endpoint determines where
+ *   data API calls go.
+ *
+ * Tokens stored at ~/.patchwork/tokens/salesforce.json (mode 0600).
+ * Client credentials read from env: SALESFORCE_CLIENT_ID, SALESFORCE_CLIENT_SECRET.
+ */
+export interface SalesforceTokens {
+    access_token: string;
+    refresh_token?: string;
+    /** Salesforce-specific. Org-unique base URL (`https://<org>.my.salesforce.com`). */
+    instance_url: string;
+    /** Identity URL — points to the user identity service for the connected user. */
+    id?: string;
+    token_type?: string;
+    scope?: string;
+    /** Salesforce returns `issued_at` as ms-epoch string; expiry isn't included. */
+    issued_at?: string;
+    /** Optional. We compute and persist this for getStatus() expiry heuristics. */
+    expiry_date?: number;
+    /** Captured identity profile fields (best-effort from the `id` endpoint). */
+    username?: string;
+    display_name?: string;
+    organization_id?: string;
+    connected_at?: string;
+    /** Stored at auth time so refresh works even if env vars are absent. */
+    _client_id?: string;
+    _client_secret?: string;
+    /** Pinned login host at auth time (sandbox vs prod). */
+    _login_host?: string;
+}
+export interface ConnectorStatus {
+    id: string;
+    status: "connected" | "disconnected" | "needs_reauth";
+    lastSync?: string;
+    username?: string;
+    instanceUrl?: string;
+}
+export interface ConnectorHandlerResult {
+    status: number;
+    body: string;
+    contentType?: string;
+    redirect?: string;
+}
+/** Normalized error categories returned by the Salesforce REST API. */
+export type NormalizedErrorKind = "auth_expired" | "permission_denied" | "not_found" | "rate_limited" | "provider_error" | "unknown_error";
+export interface NormalizedError {
+    kind: NormalizedErrorKind;
+    status: number;
+    message: string;
+    retryable: boolean;
+}
+/**
+ * Salesforce returns errors as `[{ message, errorCode }]` arrays for most
+ * REST endpoints. Pull `errorCode` into the message so the caller can route
+ * on it (most importantly, distinguish INVALID_SESSION_ID — the canonical
+ * 401 signal — from a 401 caused by some upstream gateway).
+ */
+export declare function normalizeError(status: number, body: string): NormalizedError;
+export declare function loadTokens(): SalesforceTokens | null;
+export declare function getStatus(): ConnectorStatus;
+export declare function getValidAccessToken(): Promise<string>;
+export interface SoqlQueryResult {
+    totalSize: number;
+    done: boolean;
+    records: Array<Record<string, unknown>>;
+    nextRecordsUrl?: string;
+}
+/**
+ * Execute a SOQL SELECT query. Hard-rejects any non-SELECT statement to keep
+ * this surface read-only — Salesforce SOQL supports SELECT only by definition,
+ * but defending against accidental DML-by-string-concat is cheap.
+ *
+ * Result cap defaults to 200 (Salesforce returns 2000 by default; narrowing
+ * the page size prevents accidental org-scans from blowing the rate budget).
+ */
+export declare function query(soql: string, opts?: {
+    limit?: number;
+    fetchFn?: typeof fetch;
+}): Promise<SoqlQueryResult>;
+export interface SoslSearchResult {
+    searchRecords: Array<Record<string, unknown>>;
+}
+/**
+ * Execute a SOSL search. Validates the first keyword is FIND so callers can't
+ * smuggle a different verb in.
+ */
+export declare function searchSosl(soslQuery: string, opts?: {
+    fetchFn?: typeof fetch;
+}): Promise<SoslSearchResult>;
+export declare function getObject(objectName: string, recordId: string, opts?: {
+    fetchFn?: typeof fetch;
+}): Promise<Record<string, unknown>>;
+export declare function listObjects(opts?: {
+    fetchFn?: typeof fetch;
+}): Promise<unknown>;
+export declare function describeObject(objectName: string, opts?: {
+    fetchFn?: typeof fetch;
+}): Promise<unknown>;
+export interface CreateRecordResult {
+    id: string;
+    success: boolean;
+    errors: unknown[];
+}
+export declare function createRecord(objectName: string, fields: Record<string, unknown>, opts?: {
+    fetchFn?: typeof fetch;
+}): Promise<CreateRecordResult>;
+export declare function updateRecord(objectName: string, recordId: string, fields: Record<string, unknown>, opts?: {
+    fetchFn?: typeof fetch;
+}): Promise<{
+    ok: true;
+}>;
+/** Health check — hits the API version list endpoint, which is auth-required. */
+export declare function healthCheck(fetchFn?: typeof fetch): Promise<{
+    ok: boolean;
+    status: number;
+    error?: string;
+}>;
+export declare function handleSalesforceAuthRedirect(): ConnectorHandlerResult;
+export declare function handleSalesforceCallback(code: string | null, state: string | null, error: string | null): Promise<ConnectorHandlerResult>;
+export declare function handleSalesforceTest(): Promise<ConnectorHandlerResult>;
+export declare function handleSalesforceDisconnect(): Promise<ConnectorHandlerResult>;