@almadar/integrations 2.7.0 → 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 { 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-BoDqQ89e.js';
+export { I as IntegrationFactory, g as getIntegrationFactory, r as resetIntegrationFactory } from './factory-BcFFy4JA.js';
 export { GitHubIntegration } from './integrations/github/index.js';
 
 /**
@@ -889,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>;
 }
 
 /**
@@ -1148,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 };

package/dist/index.js

@@ -278,6 +278,179 @@ function resetIntegrationFactory() {
   _factory?.reset();
   _factory = null;
 }
+var STRIPE_API_VERSION = "2025-02-24.acacia";
+function priceToTier(priceId, prices) {
+  if (priceId === prices.solo) return "solo";
+  if (priceId === prices.teams) return "teams";
+  return null;
+}
+function mapStatus(status) {
+  switch (status) {
+    case "active":
+    case "past_due":
+    case "canceled":
+    case "incomplete":
+    case "incomplete_expired":
+    case "trialing":
+    case "unpaid":
+      return status;
+    case "paused":
+      return "unpaid";
+    default: {
+      return "incomplete";
+    }
+  }
+}
+function isoFromUnix(seconds) {
+  return new Date(seconds * 1e3).toISOString();
+}
+function shapeSubscription(sub, prices) {
+  const firstItem = sub.items.data[0];
+  const priceId = firstItem?.price.id ?? "";
+  const quantity = firstItem?.quantity ?? 1;
+  const customerId = typeof sub.customer === "string" ? sub.customer : sub.customer.id;
+  return {
+    subscriptionId: sub.id,
+    customerId,
+    status: mapStatus(sub.status),
+    priceId,
+    quantity,
+    currentPeriodStart: isoFromUnix(sub.current_period_start),
+    currentPeriodEnd: isoFromUnix(sub.current_period_end),
+    cancelAtPeriodEnd: sub.cancel_at_period_end,
+    tier: priceToTier(priceId, prices)
+  };
+}
+function customerIdOf(customer) {
+  if (customer === null) return "";
+  return typeof customer === "string" ? customer : customer.id;
+}
+function verifyAndParseStripeEvent(input) {
+  const stripe = new Stripe("placeholder-only-for-webhook-utility", {
+    apiVersion: STRIPE_API_VERSION
+  });
+  let event;
+  try {
+    event = stripe.webhooks.constructEvent(
+      input.rawBody,
+      input.signature,
+      input.secret
+    );
+  } catch {
+    return { error: "bad-signature" };
+  }
+  switch (event.type) {
+    case "customer.subscription.created": {
+      const sub = event.data.object;
+      return {
+        type: "subscription.created",
+        eventId: event.id,
+        data: shapeSubscription(sub, input.prices)
+      };
+    }
+    case "customer.subscription.updated": {
+      const sub = event.data.object;
+      return {
+        type: "subscription.updated",
+        eventId: event.id,
+        data: shapeSubscription(sub, input.prices)
+      };
+    }
+    case "customer.subscription.deleted": {
+      const sub = event.data.object;
+      return {
+        type: "subscription.deleted",
+        eventId: event.id,
+        data: {
+          subscriptionId: sub.id,
+          customerId: customerIdOf(sub.customer)
+        }
+      };
+    }
+    case "invoice.payment_succeeded": {
+      const invoice = event.data.object;
+      const subRef = invoice.subscription;
+      return {
+        type: "invoice.payment_succeeded",
+        eventId: event.id,
+        data: {
+          customerId: customerIdOf(invoice.customer),
+          subscriptionId: typeof subRef === "string" ? subRef : subRef?.id ?? null,
+          paidAt: isoFromUnix(invoice.status_transitions.paid_at ?? invoice.created),
+          amountUsd: invoice.amount_paid / 100
+        }
+      };
+    }
+    case "invoice.payment_failed": {
+      const invoice = event.data.object;
+      const subRef = invoice.subscription;
+      return {
+        type: "invoice.payment_failed",
+        eventId: event.id,
+        data: {
+          customerId: customerIdOf(invoice.customer),
+          subscriptionId: typeof subRef === "string" ? subRef : subRef?.id ?? null,
+          failedAt: isoFromUnix(invoice.created),
+          reason: invoice.last_finalization_error?.message ?? "Payment failed; reason not provided by Stripe."
+        }
+      };
+    }
+    default:
+      return { error: "unknown-event-type", stripeType: event.type };
+  }
+}
+
+// src/integrations/stripe/index.ts
+var STRIPE_API_VERSION2 = "2025-02-24.acacia";
+function isoFromUnix2(seconds) {
+  return new Date(seconds * 1e3).toISOString();
+}
+function priceToTier2(priceId, prices) {
+  if (priceId === prices.solo) return "solo";
+  if (priceId === prices.teams) return "teams";
+  return null;
+}
+function mapStatus2(status) {
+  switch (status) {
+    case "active":
+    case "past_due":
+    case "canceled":
+    case "incomplete":
+    case "incomplete_expired":
+    case "trialing":
+    case "unpaid":
+      return status;
+    case "paused":
+      return "unpaid";
+    default: {
+      return "incomplete";
+    }
+  }
+}
+function shapeSubscription2(sub, prices) {
+  const firstItem = sub.items.data[0];
+  const priceId = firstItem?.price.id ?? "";
+  const quantity = firstItem?.quantity ?? 1;
+  const customerId = typeof sub.customer === "string" ? sub.customer : sub.customer.id;
+  return {
+    subscriptionId: sub.id,
+    customerId,
+    status: mapStatus2(sub.status),
+    priceId,
+    quantity,
+    currentPeriodStart: isoFromUnix2(sub.current_period_start),
+    currentPeriodEnd: isoFromUnix2(sub.current_period_end),
+    cancelAtPeriodEnd: sub.cancel_at_period_end,
+    tier: priceToTier2(priceId, prices)
+  };
+}
+function shapeCustomer(customer) {
+  return {
+    customerId: customer.id,
+    email: customer.email ?? null,
+    almadarUid: customer.metadata?.almadarUid ?? null
+  };
+}
 var StripeIntegration = class extends BaseIntegration {
   constructor(config) {
     super(config);
@@ -286,10 +459,18 @@ var StripeIntegration = class extends BaseIntegration {
       throw new Error("STRIPE_SECRET_KEY not configured");
     }
     this.client = new Stripe(apiKey, {
-      apiVersion: "2025-02-24.acacia"
+      apiVersion: STRIPE_API_VERSION2
     });
+    this.prices = {
+      solo: config.env.STRIPE_PRICE_SOLO ?? "",
+      teams: config.env.STRIPE_PRICE_TEAMS ?? ""
+    };
     this.logger.info("Stripe integration initialized");
   }
+  /** Provisioned Price IDs the integration was constructed with. */
+  getPrices() {
+    return this.prices;
+  }
   async execute(action, params) {
     const validation = this.validateParams(action, params);
     if (!validation.valid) {
@@ -305,7 +486,7 @@ var StripeIntegration = class extends BaseIntegration {
       };
     }
     const startTime = Date.now();
-    let retries = 0;
+    const retries = 0;
     try {
       let data;
       switch (action) {
@@ -334,7 +515,10 @@ var StripeIntegration = class extends BaseIntegration {
   }
   async createPaymentIntent(params) {
     const { amount, currency, metadata } = params;
-    this.logger.debug("Creating payment intent", { amount: Number(amount), currency: String(currency ?? "") });
+    this.logger.debug("Creating payment intent", {
+      amount: Number(amount),
+      currency: String(currency ?? "")
+    });
     return await this.client.paymentIntents.create({
       amount,
       currency,
@@ -343,17 +527,164 @@ var StripeIntegration = class extends BaseIntegration {
   }
   async confirmPayment(params) {
     const { paymentIntentId } = params;
-    this.logger.debug("Confirming payment", { paymentIntentId: String(paymentIntentId ?? "") });
+    this.logger.debug("Confirming payment", {
+      paymentIntentId: String(paymentIntentId ?? "")
+    });
     return await this.client.paymentIntents.confirm(paymentIntentId);
   }
   async refund(params) {
     const { paymentIntentId, amount } = params;
-    this.logger.debug("Creating refund", { paymentIntentId: String(paymentIntentId ?? ""), amount: Number(amount) });
+    this.logger.debug("Creating refund", {
+      paymentIntentId: String(paymentIntentId ?? ""),
+      amount: Number(amount)
+    });
     return await this.client.refunds.create({
       payment_intent: paymentIntentId,
       amount
     });
   }
+  // ───────────────────────────────────────────────────────────────────
+  // Typed action surface — canonical Almadar shapes only.
+  // ───────────────────────────────────────────────────────────────────
+  /** Look up an existing customer by Stripe ID. */
+  async getCustomer(customerId) {
+    this.logger.debug("Fetching customer", { customerId });
+    const customer = await this.client.customers.retrieve(customerId);
+    if (customer.deleted === true) return null;
+    return shapeCustomer(customer);
+  }
+  /**
+   * 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.
+   */
+  async createCustomer(input) {
+    this.logger.debug("Creating customer", { almadarUid: input.almadarUid });
+    const customer = await this.client.customers.create({
+      email: input.email,
+      name: input.displayName ?? void 0,
+      metadata: { almadarUid: input.almadarUid }
+    });
+    return shapeCustomer(customer);
+  }
+  /**
+   * 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.
+   */
+  async createCheckoutSession(input) {
+    const price = input.tier === "solo" ? this.prices.solo : this.prices.teams;
+    if (!price) {
+      throw new Error(`STRIPE_PRICE_${input.tier.toUpperCase()} not configured`);
+    }
+    this.logger.debug("Creating Checkout session", {
+      tier: input.tier,
+      quantity: input.quantity,
+      hasCustomer: input.customerId !== null
+    });
+    const session = await this.client.checkout.sessions.create({
+      mode: "subscription",
+      customer: input.customerId ?? void 0,
+      line_items: [{ price, quantity: input.quantity }],
+      success_url: input.successUrl,
+      cancel_url: input.cancelUrl,
+      subscription_data: {
+        metadata: input.metadata
+      },
+      automatic_tax: { enabled: true },
+      allow_promotion_codes: true
+    });
+    return {
+      url: session.url ?? "",
+      sessionId: session.id,
+      customerId: typeof session.customer === "string" ? session.customer : session.customer?.id ?? null
+    };
+  }
+  /** Create a Billing Portal session for self-service plan management. */
+  async createBillingPortalSession(input) {
+    this.logger.debug("Creating Portal session", { customerId: input.customerId });
+    const session = await this.client.billingPortal.sessions.create({
+      customer: input.customerId,
+      return_url: input.returnUrl
+    });
+    return {
+      url: session.url,
+      customerId: input.customerId
+    };
+  }
+  /** Fetch a subscription and shape it into the canonical form. */
+  async getSubscription(subscriptionId) {
+    this.logger.debug("Fetching subscription", { subscriptionId });
+    const sub = await this.client.subscriptions.retrieve(subscriptionId);
+    return shapeSubscription2(sub, this.prices);
+  }
+  /**
+   * Create a subscription directly (server-side, no Checkout). Used by
+   * P13.3 Solo → Teams upgrade flow.
+   */
+  async createSubscription(input) {
+    const price = input.tier === "solo" ? this.prices.solo : this.prices.teams;
+    if (!price) {
+      throw new Error(`STRIPE_PRICE_${input.tier.toUpperCase()} not configured`);
+    }
+    this.logger.debug("Creating subscription", {
+      customerId: input.customerId,
+      tier: input.tier,
+      quantity: input.quantity
+    });
+    const sub = await this.client.subscriptions.create({
+      customer: input.customerId,
+      items: [{ price, quantity: input.quantity }],
+      metadata: input.metadata,
+      proration_behavior: "create_prorations",
+      automatic_tax: { enabled: true }
+    });
+    return shapeSubscription2(sub, this.prices);
+  }
+  /**
+   * Update quantity or cancel-at-period-end. Used for Teams seat resize
+   * and Solo → Teams transition.
+   */
+  async updateSubscription(input) {
+    this.logger.debug("Updating subscription", { subscriptionId: input.subscriptionId });
+    const update = {
+      proration_behavior: "create_prorations"
+    };
+    if (typeof input.quantity === "number") {
+      const existing = await this.client.subscriptions.retrieve(input.subscriptionId);
+      const itemId = existing.items.data[0]?.id;
+      if (itemId !== void 0) {
+        update.items = [{ id: itemId, quantity: input.quantity }];
+      }
+    }
+    if (typeof input.cancelAtPeriodEnd === "boolean") {
+      update.cancel_at_period_end = input.cancelAtPeriodEnd;
+    }
+    const sub = await this.client.subscriptions.update(
+      input.subscriptionId,
+      update
+    );
+    return shapeSubscription2(sub, this.prices);
+  }
+  /**
+   * Cancel a subscription. Defaults to `atPeriodEnd: true` so the user
+   * keeps access until the current period ends.
+   */
+  async cancelSubscription(input) {
+    this.logger.debug("Canceling subscription", {
+      subscriptionId: input.subscriptionId,
+      atPeriodEnd: input.atPeriodEnd
+    });
+    if (input.atPeriodEnd) {
+      const sub2 = await this.client.subscriptions.update(input.subscriptionId, {
+        cancel_at_period_end: true
+      });
+      return shapeSubscription2(sub2, this.prices);
+    }
+    const sub = await this.client.subscriptions.cancel(input.subscriptionId);
+    return shapeSubscription2(sub, this.prices);
+  }
 };
 registerIntegration("stripe", StripeIntegration);
 var YouTubeIntegration = class extends BaseIntegration {
@@ -2690,6 +3021,6 @@ var DockerIntegration = class extends BaseIntegration {
 };
 registerIntegration("docker", DockerIntegration);
 
-export { BaseIntegration, CLIIntegration, ConsoleLogger, DeepAgentIntegration, DockerIntegration, EmailIntegration, GitHubIntegration, IntegrationFactory, LLMIntegration, OAuthIntegration, OtelIntegration, QueueIntegration, RedisIntegration, StorageIntegration, StripeIntegration, TwilioIntegration, YouTubeIntegration, getIntegration, getIntegrationFactory, getRegisteredIntegrations, isKnownIntegration, registerIntegration, resetIntegrationFactory, validateParams, withRetry };
+export { BaseIntegration, CLIIntegration, ConsoleLogger, DeepAgentIntegration, DockerIntegration, EmailIntegration, GitHubIntegration, IntegrationFactory, LLMIntegration, OAuthIntegration, OtelIntegration, QueueIntegration, RedisIntegration, StorageIntegration, StripeIntegration, TwilioIntegration, YouTubeIntegration, getIntegration, getIntegrationFactory, getRegisteredIntegrations, isKnownIntegration, registerIntegration, resetIntegrationFactory, validateParams, verifyAndParseStripeEvent, withRetry };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map