@almadar/integrations 2.6.3 → 2.8.0

package/dist/{BaseIntegration-DjXCkytU.d.ts → BaseIntegration-d17YX8KE.d.ts}

@@ -135,4 +135,4 @@ declare abstract class BaseIntegration {
     protected executeWithRetry<T>(fn: () => Promise<T>): Promise<T>;
 }
 
-export { BaseIntegration as B, type IntegrationParams as I, type ValidationError as V, type IntegrationLogger as a, type IntegrationErrorCode as b, type IntegrationConfig as c, type IntegrationResult as d, IntegrationError as e, type ValidationResult as f, validateParams as v };
+export { BaseIntegration as B, type IntegrationConfig as I, type ValidationError as V, IntegrationError as a, type IntegrationErrorCode as b, type IntegrationLogger as c, type IntegrationParams as d, type IntegrationResult as e, type ValidationResult as f, validateParams as v };

package/dist/{factory-BoDqQ89e.d.ts → factory-BcFFy4JA.d.ts}

@@ -1,4 +1,4 @@
-import { c as IntegrationConfig, B as BaseIntegration, I as IntegrationParams, d as IntegrationResult } from './BaseIntegration-DjXCkytU.js';
+import { I as IntegrationConfig, B as BaseIntegration, d as IntegrationParams, e as IntegrationResult } from './BaseIntegration-d17YX8KE.js';
 
 /**
  * Factory for creating and managing integration instances

package/dist/index.d.ts

@@ -1,7 +1,7 @@
-import { I as IntegrationParams, a as IntegrationLogger, b as IntegrationErrorCode, c as IntegrationConfig, B as BaseIntegration, d as IntegrationResult } from './BaseIntegration-DjXCkytU.js';
-export { e as IntegrationError, V as ValidationError, f as ValidationResult, v as validateParams } from './BaseIntegration-DjXCkytU.js';
-import { LogMeta } from '@almadar/core';
-export { I as IntegrationFactory, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-BoDqQ89e.js';
+import { d as IntegrationParams, c as IntegrationLogger, b as IntegrationErrorCode, I as IntegrationConfig, B as BaseIntegration, e as IntegrationResult } from './BaseIntegration-d17YX8KE.js';
+export { a as IntegrationError, V as ValidationError, f as ValidationResult, v as validateParams } from './BaseIntegration-d17YX8KE.js';
+import { ServiceParams, LogMeta } from '@almadar/core';
+export { I as IntegrationFactory, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-BcFFy4JA.js';
 export { GitHubIntegration } from './integrations/github/index.js';
 
 /**
@@ -385,7 +385,7 @@ type StorageActions = {
         params: {
             bucket: string;
             key: string;
-            content: unknown;
+            content: string;
             contentType?: string;
             metadata?: IntegrationParams;
         };
@@ -402,7 +402,7 @@ type StorageActions = {
             key: string;
         };
         result: {
-            content: unknown;
+            content: string;
             contentType: string;
             size: number;
             metadata: IntegrationParams;
@@ -449,7 +449,7 @@ type QueueActions = {
     enqueue: {
         params: {
             queue: string;
-            payload: unknown;
+            payload: ServiceParams;
             delay?: number;
             priority?: number;
         };
@@ -465,7 +465,7 @@ type QueueActions = {
         result: {
             job: {
                 id: string;
-                payload: unknown;
+                payload: ServiceParams;
                 enqueuedAt: number;
                 priority: number;
             } | null;
@@ -479,7 +479,7 @@ type QueueActions = {
             status: 'pending' | 'processing' | 'completed' | 'failed';
             job: {
                 id: string;
-                payload: unknown;
+                payload: ServiceParams;
                 enqueuedAt: number;
                 priority: number;
             } | null;
@@ -488,7 +488,7 @@ type QueueActions = {
     complete: {
         params: {
             jobId: string;
-            result?: unknown;
+            result?: ServiceParams;
         };
         result: {
             completed: boolean;
@@ -528,13 +528,13 @@ type RedisActions = {
             key: string;
         };
         result: {
-            value: unknown;
+            value: ServiceParams;
         };
     };
     set: {
         params: {
             key: string;
-            value: unknown;
+            value: ServiceParams;
             ttl?: number;
         };
         result: {
@@ -589,7 +589,7 @@ type RedisActions = {
     publish: {
         params: {
             channel: string;
-            message: unknown;
+            message: ServiceParams;
         };
         result: {
             receivers: number;
@@ -833,16 +833,24 @@ type IntegrationName = keyof IntegrationContracts;
 type IntegrationActionName<K extends IntegrationName> = keyof IntegrationContracts[K] & string;
 
 /**
- * Console-based logger implementation
+ * Console-based logger implementation.
+ *
+ * Routes through `@almadar/logger`'s shared gate so namespace filtering
+ * (`ALMADAR_DEBUG`, `globalThis.__ALMADAR_DEBUG__`) and the production
+ * level default (WARN+) apply uniformly with the rest of `@almadar/*`.
+ *
+ * The constructor's `level` argument is retained for backwards
+ * compatibility but is now a no-op — the active level is owned by the
+ * shared logger (compile-time + env). To filter integration logs at
+ * runtime, set `globalThis.__ALMADAR_DEBUG__ = 'almadar:integrations:*'`.
  */
 declare class ConsoleLogger implements IntegrationLogger {
-    private level;
-    constructor(level?: 'debug' | 'info' | 'warn' | 'error');
+    private readonly log;
+    constructor(_level?: 'debug' | 'info' | 'warn' | 'error');
     debug(message: string, meta?: LogMeta): void;
     info(message: string, meta?: LogMeta): void;
     warn(message: string, meta?: LogMeta): void;
     error(message: string, meta?: LogMeta): void;
-    private shouldLog;
 }
 
 /**
@@ -881,15 +889,245 @@ declare function isKnownIntegration(name: string): boolean;
 declare function getRegisteredIntegrations(): string[];
 
 /**
- * Stripe integration for payment processing
+ * Canonical Almadar shapes for the Stripe integration.
+ *
+ * Consumers (apps/builder server, future apps) MUST consume these
+ * canonical types — never raw `Stripe.*` shapes from the `stripe` SDK.
+ * The `apps/builder is an assembler` rule applies inbound webhooks as
+ * well as outbound actions: parse, narrow, and re-shape at this layer
+ * so the SDK version never appears in apps/builder code.
+ *
+ * Mirrors the pattern used by the GitHub integration (PR / Issue / Repo
+ * canonical shapes in `./github/types.ts`).
+ */
+/** Almadar-level tier identifier; mirrors `apps/builder` `TierKey`. */
+type AlmadarTier = 'free' | 'solo' | 'teams';
+/** Subscription status mapped from Stripe's lifecycle. */
+type AlmadarSubscriptionStatus = 'active' | 'past_due' | 'canceled' | 'incomplete' | 'incomplete_expired' | 'trialing' | 'unpaid';
+interface AlmadarCustomer {
+    customerId: string;
+    email: string | null;
+    /** `users/{uid}` reference stored as Stripe metadata for webhook resolution. */
+    almadarUid: string | null;
+}
+interface AlmadarSubscription {
+    subscriptionId: string;
+    customerId: string;
+    status: AlmadarSubscriptionStatus;
+    /** Stripe Price ID currently attached. */
+    priceId: string;
+    /** Seats / quantity (Solo=1, Teams=N). */
+    quantity: number;
+    /** Period boundaries in ISO timestamps. */
+    currentPeriodStart: string;
+    currentPeriodEnd: string;
+    cancelAtPeriodEnd: boolean;
+    /** Resolved tier from the price ID. `null` if price doesn't match a known tier. */
+    tier: AlmadarTier | null;
+}
+interface AlmadarCheckoutSession {
+    /** Hosted Checkout URL. Client redirects here. */
+    url: string;
+    /** Session id, useful for tracking. */
+    sessionId: string;
+    customerId: string | null;
+}
+interface AlmadarPortalSession {
+    /** Hosted Billing Portal URL. Client redirects here. */
+    url: string;
+    customerId: string;
+}
+/**
+ * Canonical webhook event surface — discriminated union over the five
+ * Stripe events apps/builder reacts to. Anything outside this set comes
+ * back as `{ error: 'unknown-event-type' }`; signature failures are
+ * `{ error: 'bad-signature' }`.
+ *
+ * IMPORTANT: NEVER expose `Stripe.Event` / `Stripe.Subscription` /
+ * `Stripe.Invoice` to consumers — that re-creates the SDK-version
+ * coupling we're explicitly breaking.
+ */
+interface AlmadarInvoicePayment {
+    customerId: string;
+    subscriptionId: string | null;
+    paidAt: string;
+    amountUsd: number;
+}
+interface AlmadarInvoiceFailure {
+    customerId: string;
+    subscriptionId: string | null;
+    failedAt: string;
+    reason: string;
+}
+type AlmadarStripeEventOk = {
+    type: 'subscription.created';
+    eventId: string;
+    data: AlmadarSubscription;
+} | {
+    type: 'subscription.updated';
+    eventId: string;
+    data: AlmadarSubscription;
+} | {
+    type: 'subscription.deleted';
+    eventId: string;
+    data: {
+        subscriptionId: string;
+        customerId: string;
+    };
+} | {
+    type: 'invoice.payment_succeeded';
+    eventId: string;
+    data: AlmadarInvoicePayment;
+} | {
+    type: 'invoice.payment_failed';
+    eventId: string;
+    data: AlmadarInvoiceFailure;
+};
+type AlmadarStripeEvent = AlmadarStripeEventOk | {
+    error: 'bad-signature';
+} | {
+    error: 'unknown-event-type';
+    stripeType: string;
+};
+/**
+ * Configuration consumed by `createCheckoutSession`. `tier` controls the
+ * price selection; `successUrl` / `cancelUrl` are app-supplied so the
+ * integration stays app-agnostic.
+ */
+interface CreateCheckoutInput {
+    customerId: string | null;
+    /** Tier the user wants to subscribe to. */
+    tier: 'solo' | 'teams';
+    /** Solo = 1; Teams = 1..3. */
+    quantity: number;
+    successUrl: string;
+    cancelUrl: string;
+    /** Optional metadata written onto the Stripe Subscription on creation. */
+    metadata: Record<string, string>;
+}
+interface CreatePortalInput {
+    customerId: string;
+    returnUrl: string;
+}
+interface CreateCustomerInput {
+    email: string;
+    almadarUid: string;
+    displayName: string | null;
+}
+interface UpdateSubscriptionInput {
+    subscriptionId: string;
+    quantity?: number;
+    cancelAtPeriodEnd?: boolean;
+}
+interface CancelSubscriptionInput {
+    subscriptionId: string;
+    /** Default `true`: cancel at period end so the user keeps access. */
+    atPeriodEnd: boolean;
+}
+/**
+ * Price → tier mapping table. The integration imports this at construction
+ * time from `IntegrationConfig.env`; consumers pass the IDs they have
+ * provisioned in their Stripe account.
+ *
+ * Solo: monthly $20 fixed. Teams: monthly $20 per seat (quantity drives total).
+ */
+interface StripePriceMap {
+    solo: string;
+    teams: string;
+}
+
+/**
+ * Verify + parse Stripe webhook signatures into canonical Almadar
+ * events. Apps/builder calls this from its `/billing/stripe-webhook`
+ * route and switches on the returned discriminated union — it never
+ * imports the `stripe` SDK or any `Stripe.*` shape.
+ *
+ * The five handled event types mirror docs §5.2 / `Almadar_Studio_Subscriptions.md`:
+ *   - customer.subscription.created
+ *   - customer.subscription.updated
+ *   - customer.subscription.deleted
+ *   - invoice.payment_succeeded
+ *   - invoice.payment_failed
+ *
+ * Anything else returns `{ error: 'unknown-event-type', stripeType: … }`
+ * so the route can acknowledge with 200 + a log line (Stripe stops
+ * retrying acknowledged events).
+ */
+
+interface VerifyAndParseInput {
+    rawBody: string | Buffer;
+    signature: string;
+    /** Stripe webhook secret (`whsec_…`). */
+    secret: string;
+    /** Map of provisioned Stripe Price IDs → Almadar tier. */
+    prices: StripePriceMap;
+}
+/**
+ * Verify Stripe's signature header against the raw body and shape the
+ * payload into a canonical `AlmadarStripeEvent`. The `stripe` SDK is
+ * only used inside this module.
+ */
+declare function verifyAndParseStripeEvent(input: VerifyAndParseInput): AlmadarStripeEvent;
+
+/**
+ * Stripe integration for payment processing and subscription billing.
+ *
+ * Two surfaces:
+ *   - Legacy `execute(action, params)` switch for the original three
+ *     PaymentIntent actions (kept for back-compat).
+ *   - New typed methods (`createCustomer`, `createCheckoutSession`,
+ *     `createSubscription`, etc.) that return canonical `Almadar*`
+ *     types. Consumers MUST prefer these — `Stripe.*` types never leak.
  */
 declare class StripeIntegration extends BaseIntegration {
     private client;
+    private prices;
     constructor(config: IntegrationConfig);
+    /** Provisioned Price IDs the integration was constructed with. */
+    getPrices(): StripePriceMap;
     execute(action: string, params: IntegrationParams): Promise<IntegrationResult>;
     private createPaymentIntent;
     private confirmPayment;
     private refund;
+    /** Look up an existing customer by Stripe ID. */
+    getCustomer(customerId: string): Promise<AlmadarCustomer | null>;
+    /**
+     * Create a Stripe Customer for the given Almadar user. `almadarUid` is
+     * stored as Stripe metadata so webhook handlers can resolve back to
+     * the right `users/{uid}` document.
+     */
+    createCustomer(input: CreateCustomerInput): Promise<AlmadarCustomer>;
+    /**
+     * Create a Stripe-hosted Checkout Session for the given tier. Client
+     * redirects the user to the returned `url`; on success Stripe fires
+     * `customer.subscription.created`, which the apps/builder webhook
+     * handler turns into a `users/{uid}.tier` write.
+     */
+    createCheckoutSession(input: CreateCheckoutInput): Promise<AlmadarCheckoutSession>;
+    /** Create a Billing Portal session for self-service plan management. */
+    createBillingPortalSession(input: CreatePortalInput): Promise<AlmadarPortalSession>;
+    /** Fetch a subscription and shape it into the canonical form. */
+    getSubscription(subscriptionId: string): Promise<AlmadarSubscription>;
+    /**
+     * Create a subscription directly (server-side, no Checkout). Used by
+     * P13.3 Solo → Teams upgrade flow.
+     */
+    createSubscription(input: {
+        customerId: string;
+        tier: 'solo' | 'teams';
+        quantity: number;
+        metadata: Record<string, string>;
+    }): Promise<AlmadarSubscription>;
+    /**
+     * Update quantity or cancel-at-period-end. Used for Teams seat resize
+     * and Solo → Teams transition.
+     */
+    updateSubscription(input: UpdateSubscriptionInput): Promise<AlmadarSubscription>;
+    /**
+     * Cancel a subscription. Defaults to `atPeriodEnd: true` so the user
+     * keeps access until the current period ends.
+     */
+    cancelSubscription(input: CancelSubscriptionInput): Promise<AlmadarSubscription>;
 }
 
 /**
@@ -1140,4 +1378,4 @@ declare class DockerIntegration extends BaseIntegration {
     private list;
 }
 
-export { BaseIntegration, type CLIActions, CLIIntegration, ConsoleLogger, type DeepAgentActions, DeepAgentIntegration, type DockerActions, DockerIntegration, type EmailActions, EmailIntegration, type GitHubActions, type IntegrationActionName, IntegrationConfig, type IntegrationConstructor, type IntegrationContracts, IntegrationErrorCode, IntegrationLogger, type IntegrationName, IntegrationResult, LLMIntegration, type LLMIntegrationActions, type OAuthActions, OAuthIntegration, type OtelActions, OtelIntegration, type QueueActions, QueueIntegration, type RedisActions, RedisIntegration, type RetryConfig, type StorageActions, StorageIntegration, type StripeActions, StripeIntegration, type TwilioActions, TwilioIntegration, type YouTubeActions, YouTubeIntegration, getIntegration, getRegisteredIntegrations, isKnownIntegration, registerIntegration, withRetry };
+export { type AlmadarCheckoutSession, type AlmadarCustomer, type AlmadarInvoiceFailure, type AlmadarInvoicePayment, type AlmadarPortalSession, type AlmadarStripeEvent, type AlmadarStripeEventOk, type AlmadarSubscription, type AlmadarSubscriptionStatus, type AlmadarTier, BaseIntegration, type CLIActions, CLIIntegration, type CancelSubscriptionInput, ConsoleLogger, type CreateCheckoutInput, type CreateCustomerInput, type CreatePortalInput, type DeepAgentActions, DeepAgentIntegration, type DockerActions, DockerIntegration, type EmailActions, EmailIntegration, type GitHubActions, type IntegrationActionName, IntegrationConfig, type IntegrationConstructor, type IntegrationContracts, IntegrationErrorCode, IntegrationLogger, type IntegrationName, IntegrationResult, LLMIntegration, type LLMIntegrationActions, type OAuthActions, OAuthIntegration, type OtelActions, OtelIntegration, type QueueActions, QueueIntegration, type RedisActions, RedisIntegration, type RetryConfig, type StorageActions, StorageIntegration, type StripeActions, StripeIntegration, type StripePriceMap, type TwilioActions, TwilioIntegration, type UpdateSubscriptionInput, type VerifyAndParseInput, type YouTubeActions, YouTubeIntegration, getIntegration, getRegisteredIntegrations, isKnownIntegration, registerIntegration, verifyAndParseStripeEvent, withRetry };