@forklaunch/implementation-ecommerce-stripe 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 forklaunch
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/lib/domain/types/index.d.ts

@@ -0,0 +1,2 @@
+export * from './payment.mapper.types';
+//# sourceMappingURL=index.d.ts.map

package/lib/domain/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../domain/types/index.ts"],"names":[],"mappings":"AAAA,cAAc,wBAAwB,CAAC"}

package/lib/domain/types/index.js

@@ -0,0 +1,18 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// domain/types/index.ts
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/lib/domain/types/payment.mapper.types.d.ts

@@ -0,0 +1,20 @@
+import { BasePaymentDtos, BasePaymentEntities } from '@forklaunch/implementation-ecommerce-base/types';
+import { EntityManager, InferEntity } from '@mikro-orm/core';
+import Stripe from 'stripe';
+/**
+ * Stripe-specific override of PaymentMappers — CreatePaymentMapper.toEntity
+ * takes the concrete Stripe.PaymentIntent (created by StripePaymentService
+ * before persistence), not the base's generic ...args: unknown[]. Same
+ * pattern as StripePlanMappers in billing overriding the generic PlanMappers.
+ */
+export type StripePaymentMappers<Entities extends BasePaymentEntities, Dto extends BasePaymentDtos> = {
+    PaymentMapper: {
+        entity: Entities['PaymentMapper'];
+        toDto: (entity: InferEntity<Entities['PaymentMapper']>) => Promise<Dto['PaymentMapper']>;
+    };
+    CreatePaymentMapper: {
+        entity: Entities['CreatePaymentMapper'];
+        toEntity: (dto: Dto['CreatePaymentMapper'], em: EntityManager, paymentIntent: Stripe.PaymentIntent, ...args: unknown[]) => Promise<InferEntity<Entities['CreatePaymentMapper']>>;
+    };
+};
+//# sourceMappingURL=payment.mapper.types.d.ts.map

package/lib/domain/types/payment.mapper.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.mapper.types.d.ts","sourceRoot":"","sources":["../../../domain/types/payment.mapper.types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,mBAAmB,EAAE,MAAM,iDAAiD,CAAC;AACvG,OAAO,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC7D,OAAO,MAAM,MAAM,QAAQ,CAAC;AAE5B;;;;;GAKG;AACH,MAAM,MAAM,oBAAoB,CAC9B,QAAQ,SAAS,mBAAmB,EACpC,GAAG,SAAS,eAAe,IACzB;IACF,aAAa,EAAE;QACb,MAAM,EAAE,QAAQ,CAAC,eAAe,CAAC,CAAC;QAClC,KAAK,EAAE,CACL,MAAM,EAAE,WAAW,CAAC,QAAQ,CAAC,eAAe,CAAC,CAAC,KAC3C,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAAC;KACpC,CAAC;IACF,mBAAmB,EAAE;QACnB,MAAM,EAAE,QAAQ,CAAC,qBAAqB,CAAC,CAAC;QACxC,QAAQ,EAAE,CACR,GAAG,EAAE,GAAG,CAAC,qBAAqB,CAAC,EAC/B,EAAE,EAAE,aAAa,EACjB,aAAa,EAAE,MAAM,CAAC,aAAa,EACnC,GAAG,IAAI,EAAE,OAAO,EAAE,KACf,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,qBAAqB,CAAC,CAAC,CAAC,CAAC;KAC5D,CAAC;CACH,CAAC"}

package/lib/eject/domain/types/index.ts

@@ -0,0 +1 @@
+export * from './payment.mapper.types';

package/lib/eject/domain/types/payment.mapper.types.ts

@@ -0,0 +1,30 @@
+import { BasePaymentDtos, BasePaymentEntities } from '@forklaunch/implementation-ecommerce-base/types';
+import { EntityManager, InferEntity } from '@mikro-orm/core';
+import Stripe from 'stripe';
+
+/**
+ * Stripe-specific override of PaymentMappers — CreatePaymentMapper.toEntity
+ * takes the concrete Stripe.PaymentIntent (created by StripePaymentService
+ * before persistence), not the base's generic ...args: unknown[]. Same
+ * pattern as StripePlanMappers in billing overriding the generic PlanMappers.
+ */
+export type StripePaymentMappers<
+  Entities extends BasePaymentEntities,
+  Dto extends BasePaymentDtos
+> = {
+  PaymentMapper: {
+    entity: Entities['PaymentMapper'];
+    toDto: (
+      entity: InferEntity<Entities['PaymentMapper']>
+    ) => Promise<Dto['PaymentMapper']>;
+  };
+  CreatePaymentMapper: {
+    entity: Entities['CreatePaymentMapper'];
+    toEntity: (
+      dto: Dto['CreatePaymentMapper'],
+      em: EntityManager,
+      paymentIntent: Stripe.PaymentIntent,
+      ...args: unknown[]
+    ) => Promise<InferEntity<Entities['CreatePaymentMapper']>>;
+  };
+};

package/lib/eject/services/index.ts

@@ -0,0 +1 @@
+export * from './payment.service';

package/lib/eject/services/payment.service.ts

@@ -0,0 +1,243 @@
+import {
+  MetricsDefinition,
+  OpenTelemetryCollector,
+  TelemetryOptions
+} from '@forklaunch/core/http';
+import { BasePaymentService } from '@forklaunch/implementation-ecommerce-base/services';
+import {
+  BasePaymentDtos,
+  BasePaymentEntities
+} from '@forklaunch/implementation-ecommerce-base/types';
+import { PaymentService } from '@forklaunch/interfaces-ecommerce/interfaces';
+import {
+  ConfirmPaymentDto,
+  CreatePaymentDto,
+  FailPaymentDto
+} from '@forklaunch/interfaces-ecommerce/types';
+import { AnySchemaValidator } from '@forklaunch/validator';
+import { EntityManager } from '@mikro-orm/core';
+import Stripe from 'stripe';
+import { StripePaymentMappers } from '../domain/types/payment.mapper.types';
+
+/**
+ * Wraps BasePaymentService with real Stripe PaymentIntent calls — the base
+ * does DB persistence, this class calls the provider API and delegates
+ * persistence back to base (same split as StripePlanService/BasePlanService
+ * in billing). Fills the payment seam: PaymentIntent drives the order
+ * toward paid; confirmation is idempotent and driven by the webhook.
+ */
+export class StripePaymentService<
+  SchemaValidator extends AnySchemaValidator,
+  Entities extends BasePaymentEntities,
+  Dto extends BasePaymentDtos = BasePaymentDtos
+> implements PaymentService
+{
+  basePaymentService: BasePaymentService<SchemaValidator, Entities, Dto>;
+  protected readonly stripeClient: Stripe;
+  protected readonly em: EntityManager;
+  protected readonly openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>;
+  protected readonly connect?: {
+    connectedAccountId: string;
+    platformFeeBps: number;
+  };
+
+  constructor(
+    stripeClient: Stripe,
+    em: EntityManager,
+    openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>,
+    schemaValidator: SchemaValidator,
+    mappers: StripePaymentMappers<Entities, Dto>,
+    options?: {
+      telemetry?: TelemetryOptions;
+      /**
+       * Stripe Connect (platform) mode. When set, PaymentIntents are created
+       * as DIRECT charges on the merchant's connected account — the merchant
+       * is the merchant of record and settles the funds — with
+       * `application_fee_amount` computed from platformFeeBps. The launch
+       * business model is NO markup (fee 0, see the Guild deck: "payments
+       * flat at launch"), so platformFeeBps defaults to 0 and the fee is
+       * omitted entirely; it exists as a dial, not a revenue assumption.
+       * When absent, behavior is unchanged: the deploy's own STRIPE_API_KEY
+       * account is the merchant (bring-your-own-key mode).
+       */
+      connect?: {
+        connectedAccountId: string;
+        platformFeeBps?: number;
+      };
+    }
+  ) {
+    this.stripeClient = stripeClient;
+    this.em = em;
+    this.openTelemetryCollector = openTelemetryCollector;
+    if (options?.connect) {
+      // Validate the fee dial here rather than trusting the caller: it comes
+      // from an env var, and every bad value fails SILENTLY downstream
+      // otherwise. A non-numeric STRIPE_PLATFORM_FEE_BPS makes Number()
+      // return NaN, `feeCents > 0` is then false, and the application fee is
+      // quietly omitted — an operator who meant to charge a fee would get
+      // none, with nothing logged. A negative value does the same. Failing
+      // at construction turns a silent misconfiguration into a startup error.
+      const platformFeeBps = options.connect.platformFeeBps ?? 0;
+      // Upper bound is exclusive: Stripe requires application_fee_amount to be
+      // strictly less than the charge, so 10000 bps (the whole charge) is never
+      // a usable value and is rejected here rather than at the first checkout.
+      if (
+        !Number.isInteger(platformFeeBps) ||
+        platformFeeBps < 0 ||
+        platformFeeBps >= 10000
+      ) {
+        throw new Error(
+          `Invalid Stripe platform fee: expected an integer from 0 to 9999 basis points, got ${platformFeeBps}. ` +
+            'Check STRIPE_PLATFORM_FEE_BPS.'
+        );
+      }
+      this.connect = {
+        connectedAccountId: options.connect.connectedAccountId,
+        platformFeeBps
+      };
+    }
+    // CreatePaymentMapper.toEntity's 3rd param is concretely Stripe.PaymentIntent
+    // here (narrower than base's generic ...args: unknown[]) — safe at runtime,
+    // this cast just satisfies the base constructor's looser declared type.
+    this.basePaymentService = new BasePaymentService(
+      em,
+      openTelemetryCollector,
+      schemaValidator,
+      mappers as unknown as ConstructorParameters<
+        typeof BasePaymentService<SchemaValidator, Entities, Dto>
+      >[3],
+      options
+    );
+  }
+
+  /**
+   * Creates the Stripe PaymentIntent, then persists the pending record with
+   * its id as providerRef. The PaymentIntent's `client_secret` is bolted
+   * onto the returned DTO (never persisted — Payment has no clientSecret
+   * column, deliberately: it's a one-time, provider-issued credential the
+   * frontend needs *right now* to actually collect the charge via
+   * Stripe.js, not something that should still be fetchable from GET
+   * /payment/:id later). This widens the return type over the
+   * PaymentService interface's `Promise<Params['PaymentDto']>` — a covariant,
+   * backward-compatible narrowing (an intersection type is always assignable
+   * to its base), the same relationship StripePaymentMappers already has to
+   * the base PaymentMappers for this class's mapper argument.
+   */
+  async createPayment(
+    paymentDto: CreatePaymentDto,
+    em?: EntityManager
+  ): Promise<Dto['PaymentMapper'] & { clientSecret?: string }> {
+    // In Connect mode this is a DIRECT charge: created on the merchant's
+    // connected account (stripeAccount request option), so the merchant is
+    // merchant-of-record and keeps the funds. The platform fee is only
+    // attached when non-zero — at launch it always is zero (no markup).
+    const requestedFeeCents = this.connect
+      ? Math.round(
+          (paymentDto.amountCents * this.connect.platformFeeBps) / 10000
+        )
+      : 0;
+    // application_fee_amount has to stay strictly below the charge. The
+    // constructor already rejects 10000 bps, but rounding can still reach the
+    // full amount on a small enough charge (1 cent at 9999 bps rounds to 1),
+    // and Stripe would reject the PaymentIntent outright. Cap it so a fee
+    // setting cannot fail a customer's checkout, and record it when it bites.
+    const feeCents = Math.min(
+      requestedFeeCents,
+      Math.max(paymentDto.amountCents - 1, 0)
+    );
+    if (feeCents !== requestedFeeCents) {
+      this.openTelemetryCollector.warn(
+        'Stripe platform fee capped below the charge amount',
+        {
+          orderId: paymentDto.orderId,
+          amountCents: paymentDto.amountCents,
+          requestedFeeCents,
+          appliedFeeCents: feeCents
+        }
+      );
+    }
+    const paymentIntent = await this.stripeClient.paymentIntents.create(
+      {
+        amount: paymentDto.amountCents,
+        currency: paymentDto.currency,
+        metadata: { orderId: paymentDto.orderId },
+        ...(this.connect && feeCents > 0
+          ? { application_fee_amount: feeCents }
+          : {})
+      },
+      this.connect
+        ? { stripeAccount: this.connect.connectedAccountId }
+        : undefined
+    );
+    const payment = await this.basePaymentService.createPayment(
+      paymentDto,
+      em ?? this.em,
+      paymentIntent
+    );
+    return {
+      ...payment,
+      clientSecret: paymentIntent.client_secret ?? undefined
+    };
+  }
+
+  /**
+   * Re-issues the client_secret for a payment that already has a live
+   * PaymentIntent, so a checkout retry resumes that intent instead of
+   * opening a second one against the same order. Two live intents for one
+   * order are both confirmable, and a customer who confirms both is charged
+   * twice — see PaymentOrderLookupService in ecommerce-stripe for the full
+   * failure mode.
+   *
+   * The secret has to be fetched back from Stripe because it is
+   * deliberately never persisted (see createPayment) — Stripe is the only
+   * place it exists after that first response.
+   *
+   * A payment with no providerRef never reached Stripe, so there is no
+   * intent to resume and the record is returned unchanged, without a
+   * secret. The caller treats that the same way it treats no payment at
+   * all: create a fresh one.
+   */
+  async resumePayment(
+    idDto: { id: string },
+    em?: EntityManager
+  ): Promise<Dto['PaymentMapper'] & { clientSecret?: string }> {
+    const payment = await this.basePaymentService.getPayment(idDto, em);
+    if (!payment.providerRef) {
+      return payment;
+    }
+    const paymentIntent = await this.stripeClient.paymentIntents.retrieve(
+      payment.providerRef,
+      {},
+      this.connect
+        ? { stripeAccount: this.connect.connectedAccountId }
+        : undefined
+    );
+    return {
+      ...payment,
+      clientSecret: paymentIntent.client_secret ?? undefined
+    };
+  }
+
+  async getPayment(
+    idDto: { id: string },
+    em?: EntityManager
+  ): Promise<Dto['PaymentMapper']> {
+    return this.basePaymentService.getPayment(idDto, em);
+  }
+
+  /** Driven by the Stripe webhook (signature-verified at the controller layer) — idempotent. */
+  async confirmPayment(
+    confirmDto: ConfirmPaymentDto,
+    em?: EntityManager
+  ): Promise<Dto['PaymentMapper']> {
+    return this.basePaymentService.confirmPayment(confirmDto, em);
+  }
+
+  /** Failed payment emits the event dunning hooks into, at the deployable-app layer. */
+  async failPayment(
+    failDto: FailPaymentDto,
+    em?: EntityManager
+  ): Promise<Dto['PaymentMapper']> {
+    return this.basePaymentService.failPayment(failDto, em);
+  }
+}

package/lib/services/index.d.ts

@@ -0,0 +1,2 @@
+export * from './payment.service';
+//# sourceMappingURL=index.d.ts.map

package/lib/services/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../services/index.ts"],"names":[],"mappings":"AAAA,cAAc,mBAAmB,CAAC"}

package/lib/services/index.js

@@ -0,0 +1,157 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// services/index.ts
+var services_exports = {};
+__export(services_exports, {
+  StripePaymentService: () => StripePaymentService
+});
+module.exports = __toCommonJS(services_exports);
+
+// services/payment.service.ts
+var import_services = require("@forklaunch/implementation-ecommerce-base/services");
+var StripePaymentService = class {
+  basePaymentService;
+  stripeClient;
+  em;
+  openTelemetryCollector;
+  connect;
+  constructor(stripeClient, em, openTelemetryCollector, schemaValidator, mappers, options) {
+    this.stripeClient = stripeClient;
+    this.em = em;
+    this.openTelemetryCollector = openTelemetryCollector;
+    if (options?.connect) {
+      const platformFeeBps = options.connect.platformFeeBps ?? 0;
+      if (!Number.isInteger(platformFeeBps) || platformFeeBps < 0 || platformFeeBps >= 1e4) {
+        throw new Error(
+          `Invalid Stripe platform fee: expected an integer from 0 to 9999 basis points, got ${platformFeeBps}. Check STRIPE_PLATFORM_FEE_BPS.`
+        );
+      }
+      this.connect = {
+        connectedAccountId: options.connect.connectedAccountId,
+        platformFeeBps
+      };
+    }
+    this.basePaymentService = new import_services.BasePaymentService(
+      em,
+      openTelemetryCollector,
+      schemaValidator,
+      mappers,
+      options
+    );
+  }
+  /**
+   * Creates the Stripe PaymentIntent, then persists the pending record with
+   * its id as providerRef. The PaymentIntent's `client_secret` is bolted
+   * onto the returned DTO (never persisted — Payment has no clientSecret
+   * column, deliberately: it's a one-time, provider-issued credential the
+   * frontend needs *right now* to actually collect the charge via
+   * Stripe.js, not something that should still be fetchable from GET
+   * /payment/:id later). This widens the return type over the
+   * PaymentService interface's `Promise<Params['PaymentDto']>` — a covariant,
+   * backward-compatible narrowing (an intersection type is always assignable
+   * to its base), the same relationship StripePaymentMappers already has to
+   * the base PaymentMappers for this class's mapper argument.
+   */
+  async createPayment(paymentDto, em) {
+    const requestedFeeCents = this.connect ? Math.round(
+      paymentDto.amountCents * this.connect.platformFeeBps / 1e4
+    ) : 0;
+    const feeCents = Math.min(
+      requestedFeeCents,
+      Math.max(paymentDto.amountCents - 1, 0)
+    );
+    if (feeCents !== requestedFeeCents) {
+      this.openTelemetryCollector.warn(
+        "Stripe platform fee capped below the charge amount",
+        {
+          orderId: paymentDto.orderId,
+          amountCents: paymentDto.amountCents,
+          requestedFeeCents,
+          appliedFeeCents: feeCents
+        }
+      );
+    }
+    const paymentIntent = await this.stripeClient.paymentIntents.create(
+      {
+        amount: paymentDto.amountCents,
+        currency: paymentDto.currency,
+        metadata: { orderId: paymentDto.orderId },
+        ...this.connect && feeCents > 0 ? { application_fee_amount: feeCents } : {}
+      },
+      this.connect ? { stripeAccount: this.connect.connectedAccountId } : void 0
+    );
+    const payment = await this.basePaymentService.createPayment(
+      paymentDto,
+      em ?? this.em,
+      paymentIntent
+    );
+    return {
+      ...payment,
+      clientSecret: paymentIntent.client_secret ?? void 0
+    };
+  }
+  /**
+   * Re-issues the client_secret for a payment that already has a live
+   * PaymentIntent, so a checkout retry resumes that intent instead of
+   * opening a second one against the same order. Two live intents for one
+   * order are both confirmable, and a customer who confirms both is charged
+   * twice — see PaymentOrderLookupService in ecommerce-stripe for the full
+   * failure mode.
+   *
+   * The secret has to be fetched back from Stripe because it is
+   * deliberately never persisted (see createPayment) — Stripe is the only
+   * place it exists after that first response.
+   *
+   * A payment with no providerRef never reached Stripe, so there is no
+   * intent to resume and the record is returned unchanged, without a
+   * secret. The caller treats that the same way it treats no payment at
+   * all: create a fresh one.
+   */
+  async resumePayment(idDto, em) {
+    const payment = await this.basePaymentService.getPayment(idDto, em);
+    if (!payment.providerRef) {
+      return payment;
+    }
+    const paymentIntent = await this.stripeClient.paymentIntents.retrieve(
+      payment.providerRef,
+      {},
+      this.connect ? { stripeAccount: this.connect.connectedAccountId } : void 0
+    );
+    return {
+      ...payment,
+      clientSecret: paymentIntent.client_secret ?? void 0
+    };
+  }
+  async getPayment(idDto, em) {
+    return this.basePaymentService.getPayment(idDto, em);
+  }
+  /** Driven by the Stripe webhook (signature-verified at the controller layer) — idempotent. */
+  async confirmPayment(confirmDto, em) {
+    return this.basePaymentService.confirmPayment(confirmDto, em);
+  }
+  /** Failed payment emits the event dunning hooks into, at the deployable-app layer. */
+  async failPayment(failDto, em) {
+    return this.basePaymentService.failPayment(failDto, em);
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  StripePaymentService
+});

package/lib/services/index.mjs

@@ -0,0 +1,130 @@
+// services/payment.service.ts
+import { BasePaymentService } from "@forklaunch/implementation-ecommerce-base/services";
+var StripePaymentService = class {
+  basePaymentService;
+  stripeClient;
+  em;
+  openTelemetryCollector;
+  connect;
+  constructor(stripeClient, em, openTelemetryCollector, schemaValidator, mappers, options) {
+    this.stripeClient = stripeClient;
+    this.em = em;
+    this.openTelemetryCollector = openTelemetryCollector;
+    if (options?.connect) {
+      const platformFeeBps = options.connect.platformFeeBps ?? 0;
+      if (!Number.isInteger(platformFeeBps) || platformFeeBps < 0 || platformFeeBps >= 1e4) {
+        throw new Error(
+          `Invalid Stripe platform fee: expected an integer from 0 to 9999 basis points, got ${platformFeeBps}. Check STRIPE_PLATFORM_FEE_BPS.`
+        );
+      }
+      this.connect = {
+        connectedAccountId: options.connect.connectedAccountId,
+        platformFeeBps
+      };
+    }
+    this.basePaymentService = new BasePaymentService(
+      em,
+      openTelemetryCollector,
+      schemaValidator,
+      mappers,
+      options
+    );
+  }
+  /**
+   * Creates the Stripe PaymentIntent, then persists the pending record with
+   * its id as providerRef. The PaymentIntent's `client_secret` is bolted
+   * onto the returned DTO (never persisted — Payment has no clientSecret
+   * column, deliberately: it's a one-time, provider-issued credential the
+   * frontend needs *right now* to actually collect the charge via
+   * Stripe.js, not something that should still be fetchable from GET
+   * /payment/:id later). This widens the return type over the
+   * PaymentService interface's `Promise<Params['PaymentDto']>` — a covariant,
+   * backward-compatible narrowing (an intersection type is always assignable
+   * to its base), the same relationship StripePaymentMappers already has to
+   * the base PaymentMappers for this class's mapper argument.
+   */
+  async createPayment(paymentDto, em) {
+    const requestedFeeCents = this.connect ? Math.round(
+      paymentDto.amountCents * this.connect.platformFeeBps / 1e4
+    ) : 0;
+    const feeCents = Math.min(
+      requestedFeeCents,
+      Math.max(paymentDto.amountCents - 1, 0)
+    );
+    if (feeCents !== requestedFeeCents) {
+      this.openTelemetryCollector.warn(
+        "Stripe platform fee capped below the charge amount",
+        {
+          orderId: paymentDto.orderId,
+          amountCents: paymentDto.amountCents,
+          requestedFeeCents,
+          appliedFeeCents: feeCents
+        }
+      );
+    }
+    const paymentIntent = await this.stripeClient.paymentIntents.create(
+      {
+        amount: paymentDto.amountCents,
+        currency: paymentDto.currency,
+        metadata: { orderId: paymentDto.orderId },
+        ...this.connect && feeCents > 0 ? { application_fee_amount: feeCents } : {}
+      },
+      this.connect ? { stripeAccount: this.connect.connectedAccountId } : void 0
+    );
+    const payment = await this.basePaymentService.createPayment(
+      paymentDto,
+      em ?? this.em,
+      paymentIntent
+    );
+    return {
+      ...payment,
+      clientSecret: paymentIntent.client_secret ?? void 0
+    };
+  }
+  /**
+   * Re-issues the client_secret for a payment that already has a live
+   * PaymentIntent, so a checkout retry resumes that intent instead of
+   * opening a second one against the same order. Two live intents for one
+   * order are both confirmable, and a customer who confirms both is charged
+   * twice — see PaymentOrderLookupService in ecommerce-stripe for the full
+   * failure mode.
+   *
+   * The secret has to be fetched back from Stripe because it is
+   * deliberately never persisted (see createPayment) — Stripe is the only
+   * place it exists after that first response.
+   *
+   * A payment with no providerRef never reached Stripe, so there is no
+   * intent to resume and the record is returned unchanged, without a
+   * secret. The caller treats that the same way it treats no payment at
+   * all: create a fresh one.
+   */
+  async resumePayment(idDto, em) {
+    const payment = await this.basePaymentService.getPayment(idDto, em);
+    if (!payment.providerRef) {
+      return payment;
+    }
+    const paymentIntent = await this.stripeClient.paymentIntents.retrieve(
+      payment.providerRef,
+      {},
+      this.connect ? { stripeAccount: this.connect.connectedAccountId } : void 0
+    );
+    return {
+      ...payment,
+      clientSecret: paymentIntent.client_secret ?? void 0
+    };
+  }
+  async getPayment(idDto, em) {
+    return this.basePaymentService.getPayment(idDto, em);
+  }
+  /** Driven by the Stripe webhook (signature-verified at the controller layer) — idempotent. */
+  async confirmPayment(confirmDto, em) {
+    return this.basePaymentService.confirmPayment(confirmDto, em);
+  }
+  /** Failed payment emits the event dunning hooks into, at the deployable-app layer. */
+  async failPayment(failDto, em) {
+    return this.basePaymentService.failPayment(failDto, em);
+  }
+};
+export {
+  StripePaymentService
+};

package/lib/services/payment.service.d.ts

@@ -0,0 +1,90 @@
+import { MetricsDefinition, OpenTelemetryCollector, TelemetryOptions } from '@forklaunch/core/http';
+import { BasePaymentService } from '@forklaunch/implementation-ecommerce-base/services';
+import { BasePaymentDtos, BasePaymentEntities } from '@forklaunch/implementation-ecommerce-base/types';
+import { PaymentService } from '@forklaunch/interfaces-ecommerce/interfaces';
+import { ConfirmPaymentDto, CreatePaymentDto, FailPaymentDto } from '@forklaunch/interfaces-ecommerce/types';
+import { AnySchemaValidator } from '@forklaunch/validator';
+import { EntityManager } from '@mikro-orm/core';
+import Stripe from 'stripe';
+import { StripePaymentMappers } from '../domain/types/payment.mapper.types';
+/**
+ * Wraps BasePaymentService with real Stripe PaymentIntent calls — the base
+ * does DB persistence, this class calls the provider API and delegates
+ * persistence back to base (same split as StripePlanService/BasePlanService
+ * in billing). Fills the payment seam: PaymentIntent drives the order
+ * toward paid; confirmation is idempotent and driven by the webhook.
+ */
+export declare class StripePaymentService<SchemaValidator extends AnySchemaValidator, Entities extends BasePaymentEntities, Dto extends BasePaymentDtos = BasePaymentDtos> implements PaymentService {
+    basePaymentService: BasePaymentService<SchemaValidator, Entities, Dto>;
+    protected readonly stripeClient: Stripe;
+    protected readonly em: EntityManager;
+    protected readonly openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>;
+    protected readonly connect?: {
+        connectedAccountId: string;
+        platformFeeBps: number;
+    };
+    constructor(stripeClient: Stripe, em: EntityManager, openTelemetryCollector: OpenTelemetryCollector<MetricsDefinition>, schemaValidator: SchemaValidator, mappers: StripePaymentMappers<Entities, Dto>, options?: {
+        telemetry?: TelemetryOptions;
+        /**
+         * Stripe Connect (platform) mode. When set, PaymentIntents are created
+         * as DIRECT charges on the merchant's connected account — the merchant
+         * is the merchant of record and settles the funds — with
+         * `application_fee_amount` computed from platformFeeBps. The launch
+         * business model is NO markup (fee 0, see the Guild deck: "payments
+         * flat at launch"), so platformFeeBps defaults to 0 and the fee is
+         * omitted entirely; it exists as a dial, not a revenue assumption.
+         * When absent, behavior is unchanged: the deploy's own STRIPE_API_KEY
+         * account is the merchant (bring-your-own-key mode).
+         */
+        connect?: {
+            connectedAccountId: string;
+            platformFeeBps?: number;
+        };
+    });
+    /**
+     * Creates the Stripe PaymentIntent, then persists the pending record with
+     * its id as providerRef. The PaymentIntent's `client_secret` is bolted
+     * onto the returned DTO (never persisted — Payment has no clientSecret
+     * column, deliberately: it's a one-time, provider-issued credential the
+     * frontend needs *right now* to actually collect the charge via
+     * Stripe.js, not something that should still be fetchable from GET
+     * /payment/:id later). This widens the return type over the
+     * PaymentService interface's `Promise<Params['PaymentDto']>` — a covariant,
+     * backward-compatible narrowing (an intersection type is always assignable
+     * to its base), the same relationship StripePaymentMappers already has to
+     * the base PaymentMappers for this class's mapper argument.
+     */
+    createPayment(paymentDto: CreatePaymentDto, em?: EntityManager): Promise<Dto['PaymentMapper'] & {
+        clientSecret?: string;
+    }>;
+    /**
+     * Re-issues the client_secret for a payment that already has a live
+     * PaymentIntent, so a checkout retry resumes that intent instead of
+     * opening a second one against the same order. Two live intents for one
+     * order are both confirmable, and a customer who confirms both is charged
+     * twice — see PaymentOrderLookupService in ecommerce-stripe for the full
+     * failure mode.
+     *
+     * The secret has to be fetched back from Stripe because it is
+     * deliberately never persisted (see createPayment) — Stripe is the only
+     * place it exists after that first response.
+     *
+     * A payment with no providerRef never reached Stripe, so there is no
+     * intent to resume and the record is returned unchanged, without a
+     * secret. The caller treats that the same way it treats no payment at
+     * all: create a fresh one.
+     */
+    resumePayment(idDto: {
+        id: string;
+    }, em?: EntityManager): Promise<Dto['PaymentMapper'] & {
+        clientSecret?: string;
+    }>;
+    getPayment(idDto: {
+        id: string;
+    }, em?: EntityManager): Promise<Dto['PaymentMapper']>;
+    /** Driven by the Stripe webhook (signature-verified at the controller layer) — idempotent. */
+    confirmPayment(confirmDto: ConfirmPaymentDto, em?: EntityManager): Promise<Dto['PaymentMapper']>;
+    /** Failed payment emits the event dunning hooks into, at the deployable-app layer. */
+    failPayment(failDto: FailPaymentDto, em?: EntityManager): Promise<Dto['PaymentMapper']>;
+}
+//# sourceMappingURL=payment.service.d.ts.map

package/lib/services/payment.service.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.service.d.ts","sourceRoot":"","sources":["../../services/payment.service.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,iBAAiB,EACjB,sBAAsB,EACtB,gBAAgB,EACjB,MAAM,uBAAuB,CAAC;AAC/B,OAAO,EAAE,kBAAkB,EAAE,MAAM,oDAAoD,CAAC;AACxF,OAAO,EACL,eAAe,EACf,mBAAmB,EACpB,MAAM,iDAAiD,CAAC;AACzD,OAAO,EAAE,cAAc,EAAE,MAAM,6CAA6C,CAAC;AAC7E,OAAO,EACL,iBAAiB,EACjB,gBAAgB,EAChB,cAAc,EACf,MAAM,wCAAwC,CAAC;AAChD,OAAO,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAC3D,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AAE5E;;;;;;GAMG;AACH,qBAAa,oBAAoB,CAC/B,eAAe,SAAS,kBAAkB,EAC1C,QAAQ,SAAS,mBAAmB,EACpC,GAAG,SAAS,eAAe,GAAG,eAAe,CAC7C,YAAW,cAAc;IAEzB,kBAAkB,EAAE,kBAAkB,CAAC,eAAe,EAAE,QAAQ,EAAE,GAAG,CAAC,CAAC;IACvE,SAAS,CAAC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IACxC,SAAS,CAAC,QAAQ,CAAC,EAAE,EAAE,aAAa,CAAC;IACrC,SAAS,CAAC,QAAQ,CAAC,sBAAsB,EAAE,sBAAsB,CAAC,iBAAiB,CAAC,CAAC;IACrF,SAAS,CAAC,QAAQ,CAAC,OAAO,CAAC,EAAE;QAC3B,kBAAkB,EAAE,MAAM,CAAC;QAC3B,cAAc,EAAE,MAAM,CAAC;KACxB,CAAC;IAEF,YACE,YAAY,EAAE,MAAM,EACpB,EAAE,EAAE,aAAa,EACjB,sBAAsB,EAAE,sBAAsB,CAAC,iBAAiB,CAAC,EACjE,eAAe,EAAE,eAAe,EAChC,OAAO,EAAE,oBAAoB,CAAC,QAAQ,EAAE,GAAG,CAAC,EAC5C,OAAO,CAAC,EAAE;QACR,SAAS,CAAC,EAAE,gBAAgB,CAAC;QAC7B;;;;;;;;;;WAUG;QACH,OAAO,CAAC,EAAE;YACR,kBAAkB,EAAE,MAAM,CAAC;YAC3B,cAAc,CAAC,EAAE,MAAM,CAAC;SACzB,CAAC;KACH,EA4CF;IAED;;;;;;;;;;;;OAYG;IACG,aAAa,CACjB,UAAU,EAAE,gBAAgB,EAC5B,EAAE,CAAC,EAAE,aAAa,GACjB,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,GAAG;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAoD3D;IAED;;;;;;;;;;;;;;;;OAgBG;IACG,aAAa,CACjB,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EACrB,EAAE,CAAC,EAAE,aAAa,GACjB,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,GAAG;QAAE,YAAY,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC,CAgB3D;IAEK,UAAU,CACd,KAAK,EAAE;QAAE,EAAE,EAAE,MAAM,CAAA;KAAE,EACrB,EAAE,CAAC,EAAE,aAAa,GACjB,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAE/B;IAED,8FAA8F;IACxF,cAAc,CAClB,UAAU,EAAE,iBAAiB,EAC7B,EAAE,CAAC,EAAE,aAAa,GACjB,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAE/B;IAED,sFAAsF;IAChF,WAAW,CACf,OAAO,EAAE,cAAc,EACvB,EAAE,CAAC,EAAE,aAAa,GACjB,OAAO,CAAC,GAAG,CAAC,eAAe,CAAC,CAAC,CAE/B;CACF"}

package/package.json

@@ -0,0 +1,65 @@
+{
+  "name": "@forklaunch/implementation-ecommerce-stripe",
+  "version": "1.0.1",
+  "description": "Stripe implementation for forklaunch ecommerce",
+  "homepage": "https://github.com/forklaunch/forklaunch-js#readme",
+  "bugs": {
+    "url": "https://github.com/forklaunch/forklaunch-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forklaunch/forklaunch-js.git"
+  },
+  "license": "MIT",
+  "author": "Forklift Technologies, Inc.",
+  "exports": {
+    "./services": {
+      "types": "./lib/services/index.d.ts",
+      "import": "./lib/services/index.mjs",
+      "require": "./lib/services/index.js",
+      "default": "./lib/services/index.js"
+    },
+    "./types": {
+      "types": "./lib/domain/types/index.d.ts",
+      "import": "./lib/domain/types/index.mjs",
+      "require": "./lib/domain/types/index.js",
+      "default": "./lib/domain/types/index.js"
+    }
+  },
+  "files": [
+    "lib/**"
+  ],
+  "dependencies": {
+    "@forklaunch/common": "^1.2.24",
+    "@forklaunch/core": "^1.5.16",
+    "@forklaunch/internal": "^1.2.26",
+    "@forklaunch/validator": "^1.2.25",
+    "@mikro-orm/core": "7.1.14",
+    "@sinclair/typebox": "^0.34.52",
+    "ajv": "^8.20.0",
+    "stripe": "^22.5.0",
+    "zod": "^4.4.3",
+    "@forklaunch/implementation-ecommerce-base": "^1.0.6",
+    "@forklaunch/interfaces-ecommerce": "^1.0.6"
+  },
+  "devDependencies": {
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
+    "depcheck": "^1.4.7",
+    "prettier": "^3.9.6",
+    "typedoc": "^0.28.20"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsgo --noEmit && tsup services/index.ts domain/types/index.ts --format cjs,esm --no-splitting --tsconfig tsconfig.json --out-dir lib --clean && tsgo -p tsconfig.build.json --emitDeclarationOnly && if [ -f eject-package.bash ]; then pnpm package:eject; fi",
+    "clean": "rm -rf lib pnpm.lock.yaml node_modules",
+    "docs": "typedoc --out docs *",
+    "format": "prettier --ignore-path=.prettierignore --config .prettierrc '**/*.{ts,tsx,json}' --write",
+    "lint": "eslint . -c eslint.config.mjs",
+    "lint:fix": "eslint . -c eslint.config.mjs --fix",
+    "package:eject": "./eject-package.bash",
+    "publish:package": "./publish-package.bash",
+    "test": "vitest --passWithNoTests"
+  }
+}