@almadar/integrations 2.23.0 → 2.25.0

package/dist/factory-BPVhvv5q.d.ts

@@ -0,0 +1,59 @@
+import { I as IntegrationConfig, B as BaseIntegration, e as IntegrationParams, f as IntegrationResult } from './BaseIntegration-MA-b4fh8.js';
+
+/**
+ * Optional per-call context for principal-scoped resolution (W4). The
+ * default — absent — means the tenant/app-wide credential set; a `principal`
+ * selects a per-principal configuration when one was registered. Additive:
+ * every existing call site is untouched.
+ */
+interface IntegrationCallContext {
+    principal?: string;
+}
+/**
+ * Factory for creating and managing integration instances
+ */
+declare class IntegrationFactory {
+    private instances;
+    private configs;
+    /**
+     * Configure an integration (doesn't instantiate yet). A `principal` scopes
+     * the config to that principal; the app-wide config (no principal) is the
+     * fallback for every principal.
+     */
+    configure(name: string, config: Omit<IntegrationConfig, 'name'>, principal?: string): void;
+    /**
+     * Get or create an integration instance. Principal-scoped lookups fall
+     * back to the app-wide config when no per-principal config exists.
+     */
+    get(name: string, principal?: string): BaseIntegration;
+    /**
+     * Execute an action on an integration
+     */
+    execute(integration: string, action: string, params: IntegrationParams, context?: IntegrationCallContext): Promise<IntegrationResult>;
+    /**
+     * Check if integration is configured
+     */
+    isConfigured(name: string, principal?: string): boolean;
+    /**
+     * Register an integration instance directly (used by mock infrastructure)
+     */
+    registerInstance(name: string, instance: BaseIntegration, principal?: string): void;
+    /**
+     * Drop the cached instance(s) for a name so the next `get` rebuilds from
+     * the current config — how a credential change goes live without restart.
+     * Configs are kept; without a name, every instance is dropped.
+     */
+    invalidate(name?: string): void;
+    /**
+     * Clear all instances (useful for testing)
+     */
+    clear(): void;
+    /**
+     * Clear all instances and configs
+     */
+    reset(): void;
+}
+declare function getIntegrationFactory(): IntegrationFactory;
+declare function resetIntegrationFactory(): void;
+
+export { type IntegrationCallContext as I, IntegrationFactory as a, getIntegrationFactory as g, resetIntegrationFactory as r };

package/dist/index.d.ts

@@ -1,8 +1,10 @@
 import { c as IntegrationLogger, b as IntegrationErrorCode, I as IntegrationConfig, B as BaseIntegration, e as IntegrationParams, f as IntegrationResult } from './BaseIntegration-MA-b4fh8.js';
 export { a as IntegrationError, d as IntegrationParamValue, V as ValidationError, g as ValidationResult, v as validateParams } from './BaseIntegration-MA-b4fh8.js';
-export { A as ArxivActions, C as CLIActions, D as DatabaseActions, a as DatabaseDriver, b as DatabaseQueryParamValue, c as DatabaseQueryParams, d as DatabaseQueryResult, e as DatabaseRow, f as DeepAgentActions, g as DockerActions, E as EmailActions, G as GitHubActions, I as IconifyActions, h as IntegrationActionName, i as IntegrationContracts, j as IntegrationName, L as LLMIntegrationActions, M as MLActions, O as OAuthActions, k as OtelActions, Q as QueueActions, R as RedisActions, S as StorageActions, l as StripeActions, T as TwilioActions, W as WikimediaActions, Y as YouTubeActions } from './contracts-CLTh6gjT.js';
+import { e as CredentialStore } from './store-CW1v7Apc.js';
+export { A as ArxivActions, C as CLIActions, a as CREDENTIAL_ENTITY_TYPE, b as CREDENTIAL_MASTER_KEY_ENV, c as CredentialEntry, d as CredentialPersistence, D as DatabaseActions, f as DatabaseDriver, g as DatabaseQueryParamValue, h as DatabaseQueryParams, i as DatabaseQueryResult, j as DatabaseRow, k as DeepAgentActions, l as DockerActions, E as EmailActions, G as GitHubActions, I as IconifyActions, m as IntegrationActionName, n as IntegrationContracts, o as IntegrationName, L as LLMIntegrationActions, M as MLActions, O as OAuthActions, p as OtelActions, Q as QueueActions, R as RedisActions, S as StorageActions, q as StripeActions, T as TwilioActions, W as WebhookActions, r as WikimediaActions, Y as YouTubeActions } from './store-CW1v7Apc.js';
 import { LogMeta } from '@almadar/core';
-export { I as IntegrationFactory, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-DTdVeyAi.js';
+import { a as IntegrationFactory } from './factory-BPVhvv5q.js';
+export { I as IntegrationCallContext, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-BPVhvv5q.js';
 export { GitHubIntegration } from './integrations/github/index.js';
 
 /**
@@ -61,6 +63,31 @@ declare function isKnownIntegration(name: string): boolean;
  */
 declare function getRegisteredIntegrations(): string[];
 
+/**
+ * The factory the host's `RuntimeIntegrationManager` configures — installed
+ * by its constructor so the `credentials.test` probe executes through the
+ * SAME factory (and therefore the same configs) as every other call-service.
+ */
+declare function installActiveFactory(factory: IntegrationFactory): void;
+declare function getActiveFactory(): IntegrationFactory | null;
+/**
+ * Install the host's credential store as the process-wide resolution source.
+ * Called once at boot (playground / generated server) after the store is
+ * constructed over the host's persistence adapter.
+ */
+declare function installCredentialStore(store: CredentialStore): void;
+/** The installed store, for the credentials admin service. */
+declare function getInstalledCredentialStore(): CredentialStore | null;
+/** Testing/reset hook. */
+declare function uninstallCredentialStore(): void;
+/**
+ * The one credential-reference resolver: store → env → undefined.
+ * `ref` is an env-var name — the same name `serviceCredentials` declares and
+ * `connectionRef` params carry. Every place that used to read
+ * `process.env[ref]` for a credential routes through here.
+ */
+declare function resolveCredentialRef(ref: string, env?: Record<string, string | undefined>): string | undefined;
+
 /**
  * Canonical Almadar shapes for the Stripe integration.
  *
@@ -341,6 +368,182 @@ declare class EmailIntegration extends BaseIntegration {
     private sendViaResend;
 }
 
+/**
+ * Outbound webhook integration — signed HTTP POST notifications to external endpoints.
+ */
+declare class WebhookIntegration extends BaseIntegration {
+    private signingSecret;
+    private timeoutMs;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private send;
+}
+
+/**
+ * Web Push integration — VAPID-signed push notifications to browser
+ * PushSubscription endpoints. VAPID details are passed per call (never via the
+ * web-push module singleton) so concurrent configs cannot contaminate each other.
+ */
+declare class PushIntegration extends BaseIntegration {
+    private vapidPublicKey;
+    private vapidPrivateKey;
+    private vapidSubject;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private send;
+}
+
+/**
+ * Verify + parse Google Calendar push notifications (watch channels) into the
+ * canonical Almadar hook event. Google sends NO body — everything rides the
+ * `X-Goog-*` headers — and offers no HMAC; the only verifiable secret is the
+ * channel token we supplied at `calendar.watch` time, so pass `expectedToken`
+ * whenever the watch was registered with one.
+ *
+ * The googleapis SDK never appears here or in any route — this module is the
+ * whole provider surface, mirroring `stripe/webhooks.ts`.
+ */
+type CalendarHookEvent = {
+    type: 'calendar.changed';
+    channelId: string;
+    resourceId: string;
+    /** `sync` (channel handshake), `exists`, or `not_exists`. */
+    resourceState: string;
+    messageNumber: number;
+} | {
+    error: 'missing-headers';
+} | {
+    error: 'bad-token';
+};
+declare function parseCalendarPushNotification(headers: Record<string, string | undefined>, expectedToken?: string): CalendarHookEvent;
+/**
+ * Hook-provider adapter for the shared `/api/hooks/:provider` ingress: maps a
+ * Google Calendar push notification to the bus event `CAL_REMOTE_CHANGED`
+ * consumed by `std-calendar-sync`. The `sync` handshake message acknowledges
+ * without dispatching (it announces the channel, not a data change).
+ */
+declare function googleCalendarHookProvider(expectedToken?: string): (input: {
+    headers: Record<string, string | undefined>;
+    rawBody: string;
+}) => {
+    event: string;
+    payload: {
+        channelId: string;
+        resourceId: string;
+        resourceState: string;
+    };
+} | {
+    error: string;
+} | {
+    ack: true;
+};
+
+/**
+ * Google Calendar integration — service account auth, optionally acting as a
+ * Workspace user via domain-wide delegation (GOOGLE_CALENDAR_SUBJECT). All
+ * event times are ISO strings on the wire; a 10-char value (YYYY-MM-DD) maps
+ * to an all-day `date`, anything longer to `dateTime`.
+ */
+declare class CalendarIntegration extends BaseIntegration {
+    private client;
+    private defaultCalendarId;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private calendarId;
+    private toEventTime;
+    private fromEventTime;
+    private listEvents;
+    private resolveEnd;
+    private createEvent;
+    private updateEvent;
+    private deleteEvent;
+    private freeBusy;
+    private watch;
+    private stopWatch;
+}
+
+/**
+ * Google Drive integration — service account auth, optionally acting as a
+ * Workspace user via domain-wide delegation (GOOGLE_DRIVE_SUBJECT). File
+ * content crosses this boundary as base64 (data URL accepted on upload).
+ */
+declare class DriveIntegration extends BaseIntegration {
+    private client;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private listFiles;
+    private getFile;
+    private uploadFile;
+    private createFolder;
+    private shareFile;
+}
+
+/**
+ * Meta Ads integration — Graph API Marketing Insights, READ-ONLY (spend and
+ * campaign listings for profitability reporting). No SDK: plain fetch with
+ * the webhook integration's 5xx-retries / 4xx-returns split.
+ */
+declare class MetaAdsIntegration extends BaseIntegration {
+    private accessToken;
+    private defaultAccountId;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private accountId;
+    private graphGet;
+    private getSpend;
+    private listCampaigns;
+}
+
+/**
+ * Accounting export integration — the generic half of "export to accounting
+ * software": shapes invoice / journal rows into import-ready CSV without
+ * committing to a vendor. A `provider` field is reserved on the config for
+ * direct DATEV/Xero/QuickBooks connectors later; the CSV column sets follow
+ * the common import templates those systems accept.
+ */
+declare class AccountingIntegration extends BaseIntegration {
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private exportRows;
+}
+
+/**
+ * Banking integration — GoCardless Bank Account Data (read-only requisition →
+ * accounts → transactions flow feeding reconciliation). Access tokens are
+ * minted per instance from the secret pair and refreshed on expiry.
+ */
+declare class BankingIntegration extends BaseIntegration {
+    private secretId;
+    private secretKey;
+    private accessToken;
+    private accessTokenExpiresAt;
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private token;
+    private gcRequest;
+    private createRequisition;
+    private listAccounts;
+    private listTransactions;
+}
+
+/**
+ * E-signature integration — DocuSign eSignature REST first, deliberately
+ * provider-pluggable: the action surface (sendEnvelope / getEnvelopeStatus /
+ * downloadDocument) is vendor-neutral and every DocuSign shape stays inside
+ * this module. `DOCUSIGN_BASE_URL` carries the account-scoped REST base;
+ * `DOCUSIGN_ACCESS_TOKEN` the OAuth token (JWT-grant rotation is the
+ * deployment's concern — the token is read per call so a rotated env value
+ * takes effect without restart).
+ */
+declare class EsignIntegration extends BaseIntegration {
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private dsRequest;
+    private sendEnvelope;
+    private getEnvelopeStatus;
+    private downloadDocument;
+}
+
 /**
  * LLM integration using @almadar/llm
  *
@@ -492,23 +695,47 @@ declare class OtelIntegration extends BaseIntegration {
 }
 
 /**
- * OAuth2/OIDC integration with in-memory mock backend.
+ * OAuth2/OIDC integration.
+ *
+ * Two backends behind one contract:
+ * - **OIDC (production)** — `openid-client` against a discovered issuer
+ *   (default Google; override via `OIDC_ISSUER_URL`), authorization-code +
+ *   PKCE, real token exchange / refresh / revocation / userinfo. Selected
+ *   whenever `OAUTH_CLIENT_ID` + `OAUTH_CLIENT_SECRET` are configured and
+ *   `OAUTH_MODE` is not `mock`.
+ * - **Mock (dev/tests)** — the original in-memory backend, kept verbatim
+ *   behind `OAUTH_MODE=mock` (or absent client credentials) so existing
+ *   tests and offline dev flows are untouched.
  *
- * This is a development/mock implementation. No actual OAuth library is used.
- * State tokens, access tokens, and refresh tokens are generated in-memory and
- * tracked via Maps. Useful for testing OAuth flows without external providers.
+ * Pending-authorization state (PKCE verifier, redirect URI) is held
+ * in-process keyed by `state` — multi-instance deployments need sticky
+ * routing between authorize and token (ledger note).
  */
 declare class OAuthIntegration extends BaseIntegration {
-    /** Maps state token -> provider for pending authorization flows */
+    /** Maps state token -> provider for pending MOCK authorization flows */
     private states;
-    /** Maps access token -> token set */
+    /** Maps access token -> token set (mock backend) */
     private tokens;
-    /** Maps refresh token -> access token for refresh lookups */
+    /** Maps refresh token -> access token for refresh lookups (mock backend) */
     private refreshIndex;
     /** Maps access token -> mock user session */
     private sessions;
+    /** Maps state -> pending OIDC authorization (real backend) */
+    private pending;
+    /** Maps access token -> ID-token subject, for userinfo subject checks */
+    private subjects;
+    /** Discovered issuer configurations, keyed by issuer URL */
+    private discovered;
+    private readonly real;
     constructor(config: IntegrationConfig);
     execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private issuerFor;
+    private configurationFor;
+    private oidcAuthorize;
+    private oidcToken;
+    private oidcRefresh;
+    private oidcRevoke;
+    private oidcUserinfo;
     /** Generate a random hex token of the given byte length. */
     private generateToken;
     /** Generate a mock user profile from a provider and access token. */
@@ -521,26 +748,57 @@ declare class OAuthIntegration extends BaseIntegration {
 }
 
 /**
- * Storage integration with in-memory backend for development/testing.
+ * The hosted credential store's service surface (W4 Tier C) — what the
+ * Owner-gated Integrations settings page calls through the NORMAL
+ * call-service path (server-side only; organisms own the access policy,
+ * per the I-16 std-atom ACL constraint).
+ *
+ * Security contract: `list` returns masked entries only (last-4, never
+ * plaintext); `set` accepts only env vars DECLARED in `serviceCredentials`
+ * for the named service (plus well-formed connection refs for `database`),
+ * so the page can never become an arbitrary env-injection surface; values
+ * are never logged.
+ */
+declare class CredentialsIntegration extends BaseIntegration {
+    constructor(config: IntegrationConfig);
+    execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
+    private declaredFor;
+    private assertSettable;
+    private list;
+    private set;
+    private remove;
+    private test;
+}
+
+/**
+ * Object storage integration — real S3-compatible backend (AWS S3, R2, MinIO,
+ * …) when `STORAGE_ACCESS_KEY_ID`/`STORAGE_SECRET_ACCESS_KEY` are configured,
+ * in-memory simulation otherwise. Production REFUSES the in-memory fallback:
+ * a missing credential must fail loudly, never simulate success (D-3).
  *
- * Provides S3-compatible object storage operations (upload, download, list,
- * delete, getSignedUrl) backed by an in-memory Map. No cloud SDK dependencies
- * are required.
+ * `upload` admits two shapes: the canonical `{ key, content }` pair and the
+ * file-form `{ file: { name, size, type, content }, acl?, maxSize? }` that
+ * lolo authors wire from UploadDropZone. The result carries `id`/`url`
+ * alongside `key` — the fields the .lolo consumers read.
  */
 declare class StorageIntegration extends BaseIntegration {
     private objects;
+    private s3;
+    private defaultBucket;
+    private publicUrlBase;
     constructor(config: IntegrationConfig);
     execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
-    /** Build a composite key from bucket and object key. */
+    private bucketOf;
     private compositeKey;
-    /** Generate a deterministic etag from content. */
     private generateEtag;
-    /** Compute the byte size of content. */
-    private computeSize;
+    /** Resolve the upload inputs from either admitted shape. */
+    private resolveUpload;
+    private publicUrl;
     private upload;
     private download;
     private list;
     private deleteObject;
+    private signUrl;
     private getSignedUrl;
 }
 
@@ -647,4 +905,4 @@ declare class ArxivIntegration extends BaseIntegration {
     private search;
 }
 
-export { type AlmadarCheckoutSession, type AlmadarCustomer, type AlmadarInvoiceFailure, type AlmadarInvoicePayment, type AlmadarPortalSession, type AlmadarStripeEvent, type AlmadarStripeEventOk, type AlmadarSubscription, type AlmadarSubscriptionStatus, type AlmadarTier, ArxivIntegration, type ArxivResult, BaseIntegration, CLIIntegration, type CancelSubscriptionInput, ConsoleLogger, type CreateCheckoutInput, type CreateCustomerInput, type CreatePortalInput, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, EmailIntegration, IconifyIntegration, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationLogger, IntegrationParams, IntegrationResult, LLMIntegration, MLIntegration, OAuthIntegration, OtelIntegration, QueueIntegration, RedisIntegration, type RetryConfig, type SqlGuardResult, StorageIntegration, StripeIntegration, type StripePriceMap, TwilioIntegration, type UpdateSubscriptionInput, type VerifyAndParseInput, WikimediaIntegration, YouTubeIntegration, assertReadOnlySelect, getIntegration, getRegisteredIntegrations, isKnownIntegration, registerIntegration, verifyAndParseStripeEvent, withRetry };
+export { AccountingIntegration, type AlmadarCheckoutSession, type AlmadarCustomer, type AlmadarInvoiceFailure, type AlmadarInvoicePayment, type AlmadarPortalSession, type AlmadarStripeEvent, type AlmadarStripeEventOk, type AlmadarSubscription, type AlmadarSubscriptionStatus, type AlmadarTier, ArxivIntegration, type ArxivResult, BankingIntegration, BaseIntegration, CLIIntegration, CalendarIntegration, type CancelSubscriptionInput, ConsoleLogger, type CreateCheckoutInput, type CreateCustomerInput, type CreatePortalInput, CredentialStore, CredentialsIntegration, DatabaseIntegration, DeepAgentIntegration, DockerIntegration, DriveIntegration, EmailIntegration, EsignIntegration, IconifyIntegration, IntegrationConfig, type IntegrationConstructor, IntegrationErrorCode, IntegrationFactory, IntegrationLogger, IntegrationParams, IntegrationResult, LLMIntegration, MLIntegration, MetaAdsIntegration, OAuthIntegration, OtelIntegration, PushIntegration, QueueIntegration, RedisIntegration, type RetryConfig, type SqlGuardResult, StorageIntegration, StripeIntegration, type StripePriceMap, TwilioIntegration, type UpdateSubscriptionInput, type VerifyAndParseInput, WebhookIntegration, WikimediaIntegration, YouTubeIntegration, assertReadOnlySelect, getActiveFactory, getInstalledCredentialStore, getIntegration, getRegisteredIntegrations, googleCalendarHookProvider, installActiveFactory, installCredentialStore, isKnownIntegration, parseCalendarPushNotification, registerIntegration, resolveCredentialRef, uninstallCredentialStore, verifyAndParseStripeEvent, withRetry };