@birtalanrobert/commerce 1.0.0

package/dist/nestjs/payment.entity.js

@@ -0,0 +1,181 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PaymentRefund = exports.Payment = void 0;
+const typeorm_1 = require("typeorm");
+const database_1 = require("@birtalanrobert/database");
+/**
+ * One movement of money between a customer and a business.
+ *
+ * **The record outlives the provider.** Amounts, dates, what it was for and who
+ * decided are all here in full rather than as identifiers to fetch: a business
+ * has to be able to produce its own takings years later, when the provider
+ * account may be closed, the API version retired, or the vendor replaced.
+ *
+ * There is deliberately **no foreign key to the subject**. One product takes a
+ * deposit against an appointment, another against a seat, a third against a
+ * table's tab — and a key to any one of them is precisely what would stop this
+ * table being shared.
+ */
+let Payment = class Payment extends database_1.BaseEntity {
+    tenantId;
+    /** What it was for, as the owning product names it: `booking:<id>`. */
+    subject;
+    method;
+    state;
+    /** Minor units, and the currency it was taken in. Never a float. */
+    amount;
+    currency;
+    /**
+     * Our cut, taken on top rather than out of the business's money.
+     *
+     * Recorded even when zero, because "this product charged nothing for that
+     * transaction" and "nobody wrote down what it charged" are different facts
+     * and only one of them survives an argument.
+     */
+    applicationFee;
+    /** Sum of everything given back. Never more than `amount`. */
+    refunded;
+    provider;
+    /** The provider's identifier, which is what a webhook arrives carrying. */
+    externalId;
+    /**
+     * The last four digits and the brand, for a person to recognise it by.
+     *
+     * Never the number, never a token that could be charged from a database
+     * dump. What a receptionist needs is "Visa ending 4242", and what a customer
+     * needs is to know which of their cards was used.
+     */
+    instrument;
+    /** When the money actually moved, which is not when the row was created. */
+    takenAt;
+    /** Why it failed, or what a person recorded about a cash payment. */
+    detail;
+    /** Who recorded it, for the payments a person entered by hand. */
+    recordedBy;
+};
+exports.Payment = Payment;
+__decorate([
+    (0, typeorm_1.Column)('uuid'),
+    __metadata("design:type", String)
+], Payment.prototype, "tenantId", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 160 }),
+    __metadata("design:type", String)
+], Payment.prototype, "subject", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 16 }),
+    __metadata("design:type", String)
+], Payment.prototype, "method", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 24, default: 'pending' }),
+    __metadata("design:type", String)
+], Payment.prototype, "state", void 0);
+__decorate([
+    (0, typeorm_1.Column)(database_1.MONEY_AMOUNT_COLUMN),
+    __metadata("design:type", String)
+], Payment.prototype, "amount", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 3 }),
+    __metadata("design:type", String)
+], Payment.prototype, "currency", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ ...database_1.MONEY_AMOUNT_COLUMN, default: '0' }),
+    __metadata("design:type", String)
+], Payment.prototype, "applicationFee", void 0);
+__decorate([
+    (0, typeorm_1.Column)({ ...database_1.MONEY_AMOUNT_COLUMN, default: '0' }),
+    __metadata("design:type", String)
+], Payment.prototype, "refunded", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 32, nullable: true }),
+    __metadata("design:type", Object)
+], Payment.prototype, "provider", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 128, nullable: true }),
+    __metadata("design:type", Object)
+], Payment.prototype, "externalId", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 40, nullable: true }),
+    __metadata("design:type", Object)
+], Payment.prototype, "instrument", void 0);
+__decorate([
+    (0, typeorm_1.Column)('timestamptz', { nullable: true }),
+    __metadata("design:type", Object)
+], Payment.prototype, "takenAt", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 400, nullable: true }),
+    __metadata("design:type", Object)
+], Payment.prototype, "detail", void 0);
+__decorate([
+    (0, typeorm_1.Column)('uuid', { nullable: true }),
+    __metadata("design:type", Object)
+], Payment.prototype, "recordedBy", void 0);
+exports.Payment = Payment = __decorate([
+    (0, typeorm_1.Entity)('mortar_payments'),
+    (0, typeorm_1.Unique)('uq_payments_tenant_id', ['tenantId', 'id']),
+    (0, typeorm_1.Index)('ix_payments_subject', ['tenantId', 'subject']),
+    (0, typeorm_1.Index)('ix_payments_taken', ['tenantId', 'takenAt']),
+    (0, typeorm_1.Index)('ix_payments_external', ['provider', 'externalId'])
+], Payment);
+/**
+ * Money given back, one row per act of giving it.
+ *
+ * Several partial refunds against one payment is ordinary — a deposit returned
+ * in part, a ticket refunded and its fee kept — and a single `refunded` column
+ * cannot say when each happened or why. The column stays as the running total,
+ * because that is what every read wants, and these rows are what explain it.
+ */
+let PaymentRefund = class PaymentRefund extends database_1.BaseEntity {
+    tenantId;
+    paymentId;
+    amount;
+    /**
+     * Why, in the words of whoever decided.
+     *
+     * Required rather than optional: "we refunded her ninety lei in March" is a
+     * question somebody asks a year later, and a blank reason is an answer
+     * nobody can defend.
+     */
+    reason;
+    externalId;
+    refundedBy;
+};
+exports.PaymentRefund = PaymentRefund;
+__decorate([
+    (0, typeorm_1.Column)('uuid'),
+    __metadata("design:type", String)
+], PaymentRefund.prototype, "tenantId", void 0);
+__decorate([
+    (0, typeorm_1.Column)('uuid'),
+    __metadata("design:type", String)
+], PaymentRefund.prototype, "paymentId", void 0);
+__decorate([
+    (0, typeorm_1.Column)(database_1.MONEY_AMOUNT_COLUMN),
+    __metadata("design:type", String)
+], PaymentRefund.prototype, "amount", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 400 }),
+    __metadata("design:type", String)
+], PaymentRefund.prototype, "reason", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 128, nullable: true }),
+    __metadata("design:type", Object)
+], PaymentRefund.prototype, "externalId", void 0);
+__decorate([
+    (0, typeorm_1.Column)('uuid', { nullable: true }),
+    __metadata("design:type", Object)
+], PaymentRefund.prototype, "refundedBy", void 0);
+exports.PaymentRefund = PaymentRefund = __decorate([
+    (0, typeorm_1.Entity)('mortar_payment_refunds'),
+    (0, typeorm_1.Index)('ix_payment_refunds_payment', ['tenantId', 'paymentId'])
+], PaymentRefund);
+//# sourceMappingURL=payment.entity.js.map

package/dist/nestjs/payment.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment.entity.js","sourceRoot":"","sources":["../../src/nestjs/payment.entity.ts"],"names":[],"mappings":"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"}

package/dist/nestjs/payout-account.entity.d.ts

@@ -0,0 +1,41 @@
+import { BaseEntity } from '@birtalanrobert/database';
+import type { PayoutStatus } from '../deposits';
+/**
+ * Where a business's money goes, and whether the provider will send it yet.
+ *
+ * **We never hold anybody's funds.** A customer pays the business directly and
+ * our fee is taken on top as an application fee — which is a hard architectural
+ * rule rather than a preference, because holding third-party money turns a
+ * software company into a regulated payments business.
+ *
+ * The consequence is this table. Until the provider has verified who the
+ * business is, there is nowhere for a payment to land, so every product that
+ * takes money on somebody's behalf has to gate its selling on the same fact.
+ */
+export declare class PayoutAccount extends BaseEntity {
+    tenantId: string;
+    /**
+     * Which provider this account is with.
+     *
+     * A column rather than an assumption, because the markets differ: a local
+     * processor with faster onboarding beats a lower fee for a restaurant that
+     * wants to be live this afternoon, and one of the seventeen will need one.
+     */
+    provider: string;
+    /** The provider's own identifier for the account. */
+    externalId: string;
+    status: PayoutStatus;
+    /**
+     * What the provider still wants, in its own words.
+     *
+     * Kept verbatim rather than translated into a status of ours. "We need a
+     * photograph of the director's identity document" is actionable; "restricted"
+     * is a support conversation, and the difference is a business that finishes
+     * onboarding on a Sunday evening rather than on Tuesday when somebody
+     * telephones them.
+     */
+    requirements: string[];
+    /** Set the first time the provider said it would pay out. */
+    readyAt: Date | null;
+}
+//# sourceMappingURL=payout-account.entity.d.ts.map

package/dist/nestjs/payout-account.entity.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payout-account.entity.d.ts","sourceRoot":"","sources":["../../src/nestjs/payout-account.entity.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAC;AACtD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAEhD;;;;;;;;;;;GAWG;AACH,qBAGa,aAAc,SAAQ,UAAU;IAE3C,QAAQ,EAAG,MAAM,CAAC;IAElB;;;;;;OAMG;IAEH,QAAQ,EAAG,MAAM,CAAC;IAElB,qDAAqD;IAErD,UAAU,EAAG,MAAM,CAAC;IAGpB,MAAM,EAAG,YAAY,CAAC;IAEtB;;;;;;;;OAQG;IAEH,YAAY,EAAG,MAAM,EAAE,CAAC;IAExB,6DAA6D;IAE7D,OAAO,EAAG,IAAI,GAAG,IAAI,CAAC;CACvB"}

package/dist/nestjs/payout-account.entity.js

@@ -0,0 +1,83 @@
+"use strict";
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PayoutAccount = void 0;
+const typeorm_1 = require("typeorm");
+const database_1 = require("@birtalanrobert/database");
+/**
+ * Where a business's money goes, and whether the provider will send it yet.
+ *
+ * **We never hold anybody's funds.** A customer pays the business directly and
+ * our fee is taken on top as an application fee — which is a hard architectural
+ * rule rather than a preference, because holding third-party money turns a
+ * software company into a regulated payments business.
+ *
+ * The consequence is this table. Until the provider has verified who the
+ * business is, there is nowhere for a payment to land, so every product that
+ * takes money on somebody's behalf has to gate its selling on the same fact.
+ */
+let PayoutAccount = class PayoutAccount extends database_1.BaseEntity {
+    tenantId;
+    /**
+     * Which provider this account is with.
+     *
+     * A column rather than an assumption, because the markets differ: a local
+     * processor with faster onboarding beats a lower fee for a restaurant that
+     * wants to be live this afternoon, and one of the seventeen will need one.
+     */
+    provider;
+    /** The provider's own identifier for the account. */
+    externalId;
+    status;
+    /**
+     * What the provider still wants, in its own words.
+     *
+     * Kept verbatim rather than translated into a status of ours. "We need a
+     * photograph of the director's identity document" is actionable; "restricted"
+     * is a support conversation, and the difference is a business that finishes
+     * onboarding on a Sunday evening rather than on Tuesday when somebody
+     * telephones them.
+     */
+    requirements;
+    /** Set the first time the provider said it would pay out. */
+    readyAt;
+};
+exports.PayoutAccount = PayoutAccount;
+__decorate([
+    (0, typeorm_1.Column)('uuid'),
+    __metadata("design:type", String)
+], PayoutAccount.prototype, "tenantId", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 32, default: 'stripe' }),
+    __metadata("design:type", String)
+], PayoutAccount.prototype, "provider", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 128 }),
+    __metadata("design:type", String)
+], PayoutAccount.prototype, "externalId", void 0);
+__decorate([
+    (0, typeorm_1.Column)('varchar', { length: 16, default: 'pending' }),
+    __metadata("design:type", String)
+], PayoutAccount.prototype, "status", void 0);
+__decorate([
+    (0, typeorm_1.Column)('jsonb', { default: () => `'[]'::jsonb` }),
+    __metadata("design:type", Array)
+], PayoutAccount.prototype, "requirements", void 0);
+__decorate([
+    (0, typeorm_1.Column)('timestamptz', { nullable: true }),
+    __metadata("design:type", Object)
+], PayoutAccount.prototype, "readyAt", void 0);
+exports.PayoutAccount = PayoutAccount = __decorate([
+    (0, typeorm_1.Entity)('mortar_payout_accounts'),
+    (0, typeorm_1.Unique)('uq_payout_accounts_tenant', ['tenantId', 'provider']),
+    (0, typeorm_1.Index)('ix_payout_accounts_external', ['provider', 'externalId'])
+], PayoutAccount);
+//# sourceMappingURL=payout-account.entity.js.map

package/dist/nestjs/payout-account.entity.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"payout-account.entity.js","sourceRoot":"","sources":["../../src/nestjs/payout-account.entity.ts"],"names":[],"mappings":";;;;;;;;;;;;AAAA,qCAAwD;AACxD,uDAAsD;AAGtD;;;;;;;;;;;GAWG;AAII,IAAM,aAAa,GAAnB,MAAM,aAAc,SAAQ,qBAAU;IAE3C,QAAQ,CAAU;IAElB;;;;;;OAMG;IAEH,QAAQ,CAAU;IAElB,qDAAqD;IAErD,UAAU,CAAU;IAGpB,MAAM,CAAgB;IAEtB;;;;;;;;OAQG;IAEH,YAAY,CAAY;IAExB,6DAA6D;IAE7D,OAAO,CAAe;CACvB,CAAA;AApCY,sCAAa;AAExB;IADC,IAAA,gBAAM,EAAC,MAAM,CAAC;;+CACG;AAUlB;IADC,IAAA,gBAAM,EAAC,SAAS,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,QAAQ,EAAE,CAAC;;+CACnC;AAIlB;IADC,IAAA,gBAAM,EAAC,SAAS,EAAE,EAAE,MAAM,EAAE,GAAG,EAAE,CAAC;;iDACf;AAGpB;IADC,IAAA,gBAAM,EAAC,SAAS,EAAE,EAAE,MAAM,EAAE,EAAE,EAAE,OAAO,EAAE,SAAS,EAAE,CAAC;;6CAChC;AAYtB;IADC,IAAA,gBAAM,EAAC,OAAO,EAAE,EAAE,OAAO,EAAE,GAAG,EAAE,CAAC,aAAa,EAAE,CAAC;;mDAC1B;AAIxB;IADC,IAAA,gBAAM,EAAC,aAAa,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,CAAC;;8CACpB;wBAnCX,aAAa;IAHzB,IAAA,gBAAM,EAAC,wBAAwB,CAAC;IAChC,IAAA,gBAAM,EAAC,2BAA2B,EAAE,CAAC,UAAU,EAAE,UAAU,CAAC,CAAC;IAC7D,IAAA,eAAK,EAAC,6BAA6B,EAAE,CAAC,UAAU,EAAE,YAAY,CAAC,CAAC;GACpD,aAAa,CAoCzB"}

package/dist/providers/port.d.ts

@@ -0,0 +1,97 @@
+/**
+ * What a payment provider has to be able to do, and nothing more.
+ *
+ * A port rather than the vendor's client, for the reason `@birtalanrobert/files`
+ * has one over S3: the day a market needs a local processor — and one will,
+ * because a restaurant that can be onboarded this afternoon beats a lower fee —
+ * nothing above this interface moves.
+ *
+ * Deliberately small. Everything that can be decided without the provider is
+ * decided without it: what a deposit comes to, whether a business may sell yet,
+ * what a refund leaves. This is only the part that genuinely needs somebody
+ * else's money-moving licence.
+ */
+/** Where a business's money goes, as the provider knows it. */
+export interface ProviderAccount {
+    readonly externalId: string;
+    readonly status: 'pending' | 'restricted' | 'ready';
+    /** What the provider still wants, in its own words. */
+    readonly requirements: readonly string[];
+}
+export interface OnboardingLink {
+    readonly url: string;
+    readonly expiresAt: Date;
+}
+export interface ChargeRequest {
+    /** The business being paid, as the provider knows it. */
+    readonly account: string;
+    readonly amount: number;
+    readonly currency: string;
+    /** Our cut, taken on top rather than out of the business's money. */
+    readonly applicationFee: number;
+    /** What it is for, carried through so a webhook can be matched back. */
+    readonly subject: string;
+    /**
+     * Whether to take the money now or only hold it.
+     *
+     * Holding is the anti-no-show mechanism: a card is authorised and charged
+     * only if a fee is actually applied, and **that decision is a human one**.
+     */
+    readonly capture: boolean;
+    readonly description?: string;
+    /** An idempotency key, so a retried request does not charge twice. */
+    readonly reference: string;
+}
+export interface ChargeResult {
+    readonly externalId: string;
+    readonly state: 'pending' | 'authorized' | 'captured' | 'failed';
+    /**
+     * Where to send the customer to finish, when the provider needs them.
+     *
+     * 3-D Secure and bank redirects are the ordinary case in both target
+     * markets rather than an exception, so a charge that returns a URL is not a
+     * failure and must not be handled as one.
+     */
+    readonly redirectUrl?: string;
+    readonly instrument?: string;
+    readonly detail?: string;
+}
+export interface RefundRequest {
+    readonly externalId: string;
+    readonly amount: number;
+    readonly reason: string;
+    readonly reference: string;
+}
+/** What a provider's webhook turned out to be about. */
+export interface ProviderEvent {
+    readonly kind: 'payment' | 'account' | 'other';
+    readonly externalId: string;
+    readonly state?: 'authorized' | 'captured' | 'failed' | 'refunded';
+    readonly accountStatus?: ProviderAccount;
+    readonly instrument?: string;
+    readonly detail?: string;
+}
+export interface PaymentProvider {
+    readonly name: string;
+    /** Starts or resumes onboarding, and says where to send the business. */
+    onboard(tenantId: string, returnUrl: string, refreshUrl: string): Promise<OnboardingLink>;
+    /** Creates the account if there is none, and reports where it stands. */
+    account(externalId: string | null, country: string, email?: string): Promise<ProviderAccount>;
+    charge(request: ChargeRequest): Promise<ChargeResult>;
+    /** Takes money that was only held. The human decision has been made. */
+    capture(externalId: string, amount?: number): Promise<ChargeResult>;
+    /** Releases a hold without taking anything. */
+    release(externalId: string): Promise<void>;
+    refund(request: RefundRequest): Promise<{
+        externalId: string;
+    }>;
+    /**
+     * Whether a webhook really came from the provider, and what it says.
+     *
+     * `undefined` rather than a thrown error: the caller's answer to a request
+     * that did not come from the provider is a flat acknowledgement, not a
+     * message describing what was wrong with the forgery.
+     */
+    verify(payload: string | Buffer, signature: string | undefined): ProviderEvent | undefined;
+}
+//# sourceMappingURL=port.d.ts.map

package/dist/providers/port.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../src/providers/port.ts"],"names":[],"mappings":"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"}

package/dist/providers/port.js

@@ -0,0 +1,16 @@
+"use strict";
+/**
+ * What a payment provider has to be able to do, and nothing more.
+ *
+ * A port rather than the vendor's client, for the reason `@birtalanrobert/files`
+ * has one over S3: the day a market needs a local processor — and one will,
+ * because a restaurant that can be onboarded this afternoon beats a lower fee —
+ * nothing above this interface moves.
+ *
+ * Deliberately small. Everything that can be decided without the provider is
+ * decided without it: what a deposit comes to, whether a business may sell yet,
+ * what a refund leaves. This is only the part that genuinely needs somebody
+ * else's money-moving licence.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=port.js.map

package/dist/providers/port.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"port.js","sourceRoot":"","sources":["../../src/providers/port.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;GAYG"}

package/dist/providers/stripe.d.ts

@@ -0,0 +1,39 @@
+import Stripe from 'stripe';
+import type { ChargeRequest, ChargeResult, OnboardingLink, PaymentProvider, ProviderAccount, ProviderEvent, RefundRequest } from './port';
+export interface StripeConnectOptions {
+    secretKey: string;
+    /** The endpoint's signing secret, as the dashboard gives it: `whsec_…`. */
+    webhookSecret?: string;
+    /** An already-built client, for tests and for a deployment that shares one. */
+    client?: Stripe;
+}
+/**
+ * Stripe Connect, as the port describes it.
+ *
+ * **Destination charges throughout.** The money is created on our platform
+ * account and transferred immediately to the business, with our cut taken as an
+ * application fee — which is what keeps this a software company rather than a
+ * regulated one, and what lets the business see its own payouts in its own
+ * Stripe dashboard.
+ *
+ * Everything the provider does *not* need to decide is decided before this file
+ * is reached: what a deposit comes to, whether a business may sell, what a
+ * refund leaves. What is here is the part that genuinely needs somebody else's
+ * money-moving licence.
+ */
+export declare class StripeConnect implements PaymentProvider {
+    private readonly options;
+    readonly name = "stripe";
+    private readonly stripe;
+    constructor(options: StripeConnectOptions);
+    account(externalId: string | null, country: string, email?: string): Promise<ProviderAccount>;
+    onboard(externalId: string, returnUrl: string, refreshUrl: string): Promise<OnboardingLink>;
+    charge(request: ChargeRequest): Promise<ChargeResult>;
+    capture(externalId: string, amount?: number): Promise<ChargeResult>;
+    release(externalId: string): Promise<void>;
+    refund(request: RefundRequest): Promise<{
+        externalId: string;
+    }>;
+    verify(payload: string | Buffer, signature: string | undefined): ProviderEvent | undefined;
+}
+//# sourceMappingURL=stripe.d.ts.map

package/dist/providers/stripe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"stripe.d.ts","sourceRoot":"","sources":["../../src/providers/stripe.ts"],"names":[],"mappings":"AAAA,OAAO,MAAM,MAAM,QAAQ,CAAC;AAC5B,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,cAAc,EACd,eAAe,EACf,eAAe,EACf,aAAa,EACb,aAAa,EACd,MAAM,QAAQ,CAAC;AAEhB,MAAM,WAAW,oBAAoB;IACnC,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,+EAA+E;IAC/E,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;;;;;;;;GAaG;AACH,qBAAa,aAAc,YAAW,eAAe;IAIvC,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,QAAQ,CAAC,IAAI,YAAY;IACzB,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;gBAEH,OAAO,EAAE,oBAAoB;IAIpD,OAAO,CACX,UAAU,EAAE,MAAM,GAAG,IAAI,EACzB,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,eAAe,CAAC;IAarB,OAAO,CACX,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,cAAc,CAAC;IAkBpB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC,YAAY,CAAC;IAiCrD,OAAO,CAAC,UAAU,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IAanE,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAI1C,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,OAAO,CAAC;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,CAAC;IAarE,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,aAAa,GAAG,SAAS;CAoB3F"}