@stratacommerce/stripe-connect 0.0.0-stage → 0.1.0

package/dist/provider.js

@@ -0,0 +1,195 @@
+import { isDeepStrictEqual } from 'node:util';
+import { and, eq } from 'drizzle-orm';
+import { AppError } from '@stratacommerce/extension-sdk';
+import { connectConfigurationSchema, connectFactsPageSchema, connectFactsAckResultSchema, CONNECT_API_BASE, CONNECT_API_PATHS, connectOperationResultSchema, connectPath } from '@stratacommerce/hub-protocol';
+import { CONNECT_PROVIDER, connectIdentity, connectScopeOf } from './identity.js';
+import { enrollments, financialFacts } from './schema.js';
+// Core never calls Stripe. The Hub holds the platform key; this provider
+// calls the Hub's Connect API with the enrollment's payment client token.
+export class ConnectHubClient {
+    origin;
+    token;
+    transport;
+    constructor(origin, token, transport = fetch) {
+        this.origin = origin;
+        this.token = token;
+        this.transport = transport;
+    }
+    async request(path, body) {
+        if (!path.startsWith(`${CONNECT_API_BASE}/`) || !/^[a-zA-Z0-9/?=&%_.-]+$/.test(path) || new URL(path, this.origin).origin !== this.origin)
+            throw new AppError('Invalid payment service path', 'PAYMENT_SCOPE_INVALID', 400);
+        try {
+            const response = await this.transport(`${this.origin}${path}`, { method: body === undefined ? 'GET' : 'POST', headers: { Authorization: `Bearer ${this.token}`, ...(body === undefined ? {} : { 'Content-Type': 'application/json' }) },
+                ...(body === undefined ? {} : { body: JSON.stringify(body) }), redirect: 'error', cache: 'no-store', signal: AbortSignal.timeout(15000) });
+            if (!response.ok)
+                throw new AppError('Strata payment service is unavailable; retry this payment operation', response.status === 409 ? 'PAYMENT_AUTHORIZATION_UNAVAILABLE' : 'PAYMENT_UNAVAILABLE', response.status >= 500 ? 503 : 409);
+            const bytes = await response.text();
+            if (bytes.length > 1048576)
+                throw Error();
+            return JSON.parse(bytes);
+        }
+        catch (error) {
+            if (error instanceof AppError)
+                throw error;
+            throw new AppError('Strata payment service is unavailable; retry this payment operation', 'PAYMENT_UNAVAILABLE', 503);
+        }
+    }
+}
+export class ConnectPaymentProvider {
+    services;
+    identity;
+    recipientId;
+    makeClient;
+    name = CONNECT_PROVIDER;
+    accountId;
+    scope;
+    constructor(services, identity, recipientId, makeClient) {
+        this.services = services;
+        this.identity = identity;
+        this.recipientId = recipientId;
+        this.makeClient = makeClient;
+        this.scope = connectScopeOf(identity);
+        this.accountId = this.scope.stripeAccountId;
+    }
+    get db() { return this.services.ctx.db; }
+    async client() {
+        if (this.makeClient)
+            return this.makeClient();
+        const enrollment = await this.services.enrollments.credentials(this.recipientId);
+        if (enrollment.id !== this.identity.connectionId && !enrollment.recoveryBindingIds.includes(this.identity.connectionId))
+            throw new AppError('Historical payment recovery was not approved', 'PAYMENT_SCOPE_INVALID', 409);
+        return new ConnectHubClient(enrollment.scope.hubOrigin, enrollment.token);
+    }
+    async original(paymentIntentId) {
+        const rows = await this.services.ctx.payments.attemptsForSession(paymentIntentId);
+        const row = rows.find((r) => r.provider === CONNECT_PROVIDER && isDeepStrictEqual(r.identity, this.identity));
+        if (!row)
+            throw new AppError('Original payment attempt not found', 'PAYMENT_SCOPE_INVALID', 409);
+        return row;
+    }
+    async sync() {
+        const client = await this.client();
+        for (let page = 0; page < 20; page++) {
+            const response = connectFactsPageSchema.safeParse(await client.request(CONNECT_API_PATHS.facts));
+            if (!response.success)
+                throw new AppError('Invalid payment facts', 'PAYMENT_FACTS_INVALID', 503);
+            const ids = [];
+            for (const delivery of response.data.deliveries)
+                ids.push((await this.services.facts.receive(delivery)).deliveryId);
+            if (ids.length && !connectFactsAckResultSchema.safeParse(await client.request(CONNECT_API_PATHS.factsAck, { deliveryIds: ids })).success)
+                throw new AppError('Invalid payment acknowledgement', 'PAYMENT_FACTS_INVALID', 503);
+            if (ids.length < 100)
+                return;
+        }
+        throw new AppError('Payment backlog needs reconciliation', 'PAYMENT_BACKLOG_PENDING', 503);
+    }
+    async createSession(input) {
+        const client = await this.client(), result = connectOperationResultSchema.parse(await client.request(CONNECT_API_PATHS.checkouts, { operationId: input.attemptId, attemptId: input.attemptId, orderReference: input.orderId, amountMinor: input.totalCents, currency: input.currency }));
+        if (!isDeepStrictEqual(result.scope, this.scope) || result.operationId !== input.attemptId || result.amountMinor !== input.totalCents || result.currency !== input.currency)
+            throw new AppError('Payment response scope does not match', 'PAYMENT_SCOPE_INVALID', 409);
+        if (!result.paymentIntentId || !result.clientSecret || result.state !== 'succeeded')
+            throw new AppError('Payment outcome requires recovery; retry this checkout', 'PAYMENT_OUTCOME_UNKNOWN', 503);
+        const configuration = connectConfigurationSchema.safeParse(await client.request(CONNECT_API_PATHS.configuration));
+        if (!configuration.success || !isDeepStrictEqual(configuration.data.scope, this.scope))
+            throw new AppError('Payment public configuration does not match', 'PAYMENT_SCOPE_INVALID', 409);
+        const config = configuration.data;
+        return { sessionId: result.paymentIntentId, accountId: this.accountId,
+            client: { clientSecret: result.clientSecret, publishableKey: config.publishableKey, stripeAccount: this.accountId, livemode: result.scope.livemode, contextId: result.scope.contextId } };
+    }
+    async processRefund(input) {
+        const original = await this.original(input.providerSessionId), client = await this.client();
+        const result = connectOperationResultSchema.parse(await client.request(CONNECT_API_PATHS.refunds, { operationId: input.operationId, originalPaymentId: original.id, amountMinor: input.amountCents }));
+        if (!isDeepStrictEqual(result.scope, this.scope) || result.paymentId !== original.id || result.operationId !== input.operationId || result.amountMinor !== input.amountCents)
+            throw new AppError('Refund response does not match', 'PAYMENT_SCOPE_INVALID', 409);
+        if (result.state === 'failed')
+            throw new AppError('Provider rejected this refund', 'REFUND_REJECTED', 400);
+        if (!result.providerObjectId || result.state !== 'succeeded')
+            throw new AppError('Refund outcome needs reconciliation', 'PAYMENT_OUTCOME_UNKNOWN', 503);
+        const status = result.financialStatus;
+        return { refundId: result.providerObjectId, amountCents: result.amountMinor, currency: result.currency,
+            status: status === 'succeeded' || status === 'failed' || status === 'canceled' || status === 'requires_action' ? status : 'pending', raw: {} };
+    }
+    async cancelSession(paymentIntentId) { await this.cancelAttempt((await this.original(paymentIntentId)).id); }
+    async cancelAttempt(attemptId) {
+        const result = connectOperationResultSchema.parse(await (await this.client()).request(connectPath(CONNECT_API_PATHS.cancel, attemptId), {}));
+        if (!isDeepStrictEqual(result.scope, this.scope))
+            throw new AppError('Cancellation scope does not match', 'PAYMENT_SCOPE_INVALID', 409);
+        if (result.financialStatus === 'succeeded')
+            throw new AppError('Payment captured before cancellation', 'PAYMENT_ALREADY_CAPTURED', 409);
+        if (result.financialStatus !== 'canceled')
+            throw new AppError('Payment cancellation needs recovery', 'PAYMENT_CANCEL_PENDING', 503);
+    }
+    async getCapture(paymentIntentId) {
+        const original = await this.original(paymentIntentId);
+        await (await this.client()).request(connectPath(CONNECT_API_PATHS.operation, original.id));
+        await this.sync();
+        const rows = await this.db.select().from(financialFacts).where(and(eq(financialFacts.originalBindingId, this.identity.connectionId), eq(financialFacts.paymentIntentId, paymentIntentId), eq(financialFacts.kind, 'capture')));
+        const fact = rows[0]?.fact;
+        if (!fact || fact.kind !== 'capture')
+            throw new AppError('Capture is not confirmed by signed facts', 'CAPTURE_UNCONFIRMED', 409);
+        return { provider: this.name, identity: this.identity, accountId: this.accountId, providerSessionId: paymentIntentId, providerPaymentId: paymentIntentId, amountCents: fact.amountMinor, currency: fact.currency, raw: {} };
+    }
+    async getRefunds(paymentIntentId) {
+        const original = await this.original(paymentIntentId);
+        await (await this.client()).request(connectPath(CONNECT_API_PATHS.operation, original.id));
+        await this.sync();
+        const rows = await this.db.select().from(financialFacts).where(and(eq(financialFacts.originalBindingId, this.identity.connectionId), eq(financialFacts.paymentIntentId, paymentIntentId), eq(financialFacts.kind, 'refund')));
+        return rows.flatMap(({ fact }) => fact.kind === 'refund' ? [{ provider: this.name, identity: this.identity, accountId: this.accountId, refundId: fact.objectId, providerSessionId: paymentIntentId, amountCents: fact.amountMinor, currency: fact.currency, status: fact.status, version: fact.factVersion, operationId: fact.operationId, raw: {} }] : []);
+    }
+    async getRefund(refundId) {
+        const [fact] = await this.db.select().from(financialFacts).where(and(eq(financialFacts.originalBindingId, this.identity.connectionId), eq(financialFacts.kind, 'refund'), eq(financialFacts.objectId, refundId)));
+        if (!fact)
+            throw new AppError('Signed refund fact is pending', 'PAYMENT_FACT_PENDING', 503);
+        const facts = await this.getRefunds(fact.paymentIntentId);
+        const found = facts.find((r) => r.refundId === refundId);
+        if (!found)
+            throw new AppError('Signed refund fact is pending', 'PAYMENT_FACT_PENDING', 503);
+        return found;
+    }
+}
+/** The registration for `stripe-connect:card`. */
+export function connectRegistration(services) {
+    const db = services.ctx.db;
+    const registration = {
+        // USD needs at least 50 cents on a card, so a gift card leaves that much.
+        minimumChargeCents: { usd: 50 },
+        async publicConfiguration({ config }) {
+            // With the Hub off the method is unavailable. Recorded payments stay.
+            if ((await services.ctx.hub.status()).state === 'disabled')
+                return null;
+            const provider = await registration.factory({ config });
+            if (!provider)
+                return null;
+            const scope = connectScopeOf(provider.identity);
+            const enrollment = await services.enrollments.credentials(provider.identity.connectionId);
+            const publicConfig = connectConfigurationSchema.safeParse(await new ConnectHubClient(enrollment.scope.hubOrigin, enrollment.token).request(CONNECT_API_PATHS.configuration));
+            if (!publicConfig.success || !isDeepStrictEqual(publicConfig.data.scope, scope))
+                return null;
+            return { publishableKey: publicConfig.data.publishableKey, stripeAccount: provider.accountId, livemode: scope.livemode };
+        },
+        // Checkout uses the enrollment in the method's configuration. A recorded
+        // payment uses its original enrollment, or the active enrollment approved
+        // to recover it.
+        async factory({ config, identity }) {
+            let recipientId = identity?.connectionId ?? config.paymentBindingId;
+            if (!recipientId)
+                return null;
+            const [original] = await db.select().from(enrollments).where(eq(enrollments.id, recipientId));
+            if (!original || (identity && !isDeepStrictEqual(original.scope, connectScopeOf(identity))))
+                return null;
+            if (!identity && original.state !== 'active')
+                return null;
+            if (!['active', 'disabled'].includes(original.state) || !original.tokenBox) {
+                const candidates = await db.select().from(enrollments);
+                const replacement = candidates.find((c) => ['active', 'disabled'].includes(c.state) && !!c.tokenBox && c.recoveryBindingIds.includes(original.id) && c.scope.hubAccountId === original.scope.hubAccountId && c.scope.hubStoreId === original.scope.hubStoreId && c.scope.hubEnvironmentId === original.scope.hubEnvironmentId);
+                if (!replacement)
+                    return null;
+                recipientId = replacement.id;
+            }
+            // Runtime validation and local revocation happen before any Hub network request.
+            await services.enrollments.credentials(recipientId);
+            return new ConnectPaymentProvider(services, identity ?? connectIdentity(original.id, original.scope), recipientId);
+        },
+    };
+    return registration;
+}

package/dist/routes.d.ts

@@ -0,0 +1,5 @@
+import type { ExtensionContext } from '@stratacommerce/extension-sdk';
+import type { Enrollments } from './enrollments.js';
+import type { Facts } from './facts.js';
+export declare function registerHubRoutes(ctx: ExtensionContext, enrollments: Enrollments, facts: Facts): void;
+export declare function registerAdminRoutes(ctx: ExtensionContext, enrollments: Enrollments, facts: Facts): void;

package/dist/routes.js

@@ -0,0 +1,54 @@
+import { z } from 'zod';
+import { CONNECT_PATHS } from '@stratacommerce/hub-protocol';
+import { hubOff } from './identity.js';
+const prefix = '/hub/v1/extensions/stripe-connect';
+/** A CONNECT_PATHS entry relative to this extension's Hub route mount. */
+const hubPath = (path) => { if (!path.startsWith(prefix))
+    throw new Error(`Connect path outside the extension: ${path}`); return path.slice(prefix.length); };
+const enabledBody = z.object({ enabled: z.boolean() });
+const noStore = (res) => res.header('Cache-Control', 'no-store');
+// Hub-to-store calls carry the Hub token of the active link; core checks it
+// before these handlers run. Fact deliveries are also signed.
+export function registerHubRoutes(ctx, enrollments, facts) {
+    ctx.routes.addHubRoute('POST', hubPath(CONNECT_PATHS.challenge), async (req, res) => res.json(await enrollments.recordChallenge(req.link, req.body)));
+    ctx.routes.addHubRoute('GET', hubPath(CONNECT_PATHS.approval), async (req, res) => res.json(await enrollments.approval(req.link, req.params.bindingId)));
+    ctx.routes.addHubRoute('POST', hubPath(CONNECT_PATHS.enroll), async (req, res) => res.json(await enrollments.enroll(req.link, req.params.bindingId, req.body)), { bodyLimit: 1024 });
+    ctx.routes.addHubRoute('POST', hubPath(CONNECT_PATHS.keys), async (req, res) => res.json(await enrollments.refreshKeys(req.link, req.params.bindingId, req.body)));
+    // The signed facts schema allows 32 KiB of payload plus signature and envelope.
+    ctx.routes.addHubRoute('POST', hubPath(CONNECT_PATHS.facts), async (req, res) => {
+        const receipt = await facts.receive(req.body);
+        await facts.projectPending();
+        res.json(receipt);
+    }, { bodyLimit: 34 * 1024 });
+}
+// Order facts follow core's order read permission; payment settings are owner-only.
+export function registerAdminRoutes(ctx, enrollments, facts) {
+    const owner = { minRole: 'owner' };
+    ctx.routes.addAdminRoute('GET', '/status', async (_req, res) => noStore(res).json({ hub: (await ctx.hub.status()).state, connections: await enrollments.status() }), owner);
+    ctx.routes.addAdminRoute('GET', '/financials', async (_req, res) => noStore(res).json(await facts.latest()), owner);
+    ctx.routes.addAdminRoute('GET', '/orders/:orderId/financials', async (req, res) => noStore(res).json(await facts.forOrder(z.string().uuid().parse(req.params.orderId))), { minRole: 'support' });
+    ctx.routes.addAdminRoute('POST', '/approvals/:id/approve', async (req, res) => noStore(res).json(await enrollments.approve(req.actor.id, req.params.id, req.body)), owner);
+    ctx.routes.addAdminRoute('POST', '/connections/:id/revoke', async (req, res) => noStore(res).json(await enrollments.revoke(req.params.id)), owner);
+    ctx.routes.addAdminRoute('POST', '/connections/:id/enabled', async (req, res) => noStore(res).json(await enrollments.setEnabled(req.params.id, enabledBody.parse(req.body).enabled)), owner);
+    ctx.routes.addAdminRoute('POST', '/disconnect', async (_req, res) => {
+        for (const row of await enrollments.status())
+            if (['active', 'disabled'].includes(row.state))
+                await enrollments.revoke(row.id);
+        await ctx.payments.setMethod('card', { enabled: false, config: {} });
+        noStore(res).json({ connected: false });
+    }, owner);
+    // Connect onboarding needs a usable store link whose API address the Hub has confirmed.
+    ctx.routes.addAdminRoute('GET', '/connect-url', async (_req, res) => {
+        const { state, link } = await ctx.hub.status();
+        noStore(res);
+        if (state === 'disabled')
+            return res.json({ available: false, reason: hubOff().message });
+        if (state === 'unusable')
+            return res.json({ available: false, reason: 'This store’s Hub link is unusable in this environment. Connect it to Strata Hub again.' });
+        if (state !== 'connected' || !link)
+            return res.json({ available: false, reason: 'Connect this store to Strata Hub first.' });
+        if (!link.addressConfirmed)
+            return res.json({ available: false, reason: 'Confirm the store’s API address with Strata Hub first. Payments need a public API address.' });
+        res.json({ available: true, url: `${link.hubOrigin}/accounts/${encodeURIComponent(link.account.id)}/sites/${link.store.id}/payments?environmentId=${link.environment.id}` });
+    }, owner);
+}