@beignet/core 0.0.12 → 0.0.14

package/dist/locks/index.js

@@ -0,0 +1,248 @@
+/**
+ * @beignet/core/locks
+ *
+ * Provider-neutral distributed lock and lease primitives for Beignet apps.
+ */
+import { createProvider, createProviderInstrumentation, } from "../providers/index.js";
+/**
+ * Error thrown when a lease option is invalid.
+ */
+export class LeaseOptionsError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "LeaseOptionsError";
+    }
+}
+/**
+ * Create an in-memory locks port for tests and single-process development.
+ */
+export function createMemoryLocks(options = {}) {
+    const leases = new Map();
+    const now = options.now ?? (() => new Date());
+    const sleep = options.sleep ?? defaultSleep;
+    const createOwnerToken = options.createOwnerToken ?? createRandomToken;
+    let nextFencingToken = 1;
+    const port = {
+        leases,
+        async acquire(key, acquireOptions) {
+            validateAcquireOptions(key, acquireOptions);
+            const waitMs = acquireOptions.waitMs ?? 0;
+            const retryDelayMs = acquireOptions.retryDelayMs ?? 50;
+            const deadline = now().getTime() + waitMs;
+            const ownerToken = acquireOptions.ownerToken ?? createOwnerToken();
+            while (true) {
+                pruneExpired(key, leases, now);
+                if (!leases.has(key)) {
+                    const record = {
+                        key,
+                        ownerToken,
+                        expiresAt: new Date(now().getTime() + acquireOptions.ttlMs),
+                        ttlMs: acquireOptions.ttlMs,
+                        fencingToken: nextFencingToken++,
+                        metadata: acquireOptions.metadata,
+                    };
+                    leases.set(key, record);
+                    return {
+                        acquired: true,
+                        lease: createMemoryLease(port, record, now),
+                    };
+                }
+                if (waitMs <= 0) {
+                    return { acquired: false, reason: "unavailable" };
+                }
+                const remainingMs = deadline - now().getTime();
+                if (remainingMs <= 0) {
+                    pruneExpired(key, leases, now);
+                    if (!leases.has(key))
+                        continue;
+                    return { acquired: false, reason: "timeout" };
+                }
+                await sleep(Math.min(retryDelayMs, remainingMs));
+            }
+        },
+        async withLease(key, acquireOptions, fn) {
+            const result = await port.acquire(key, acquireOptions);
+            if (!result.acquired)
+                return undefined;
+            try {
+                return await fn({ lease: result.lease });
+            }
+            finally {
+                await result.lease.release();
+            }
+        },
+        restore(key, ownerToken) {
+            if (!key)
+                throw new LeaseOptionsError("Lease key is required.");
+            if (!ownerToken) {
+                throw new LeaseOptionsError("Lease owner token is required.");
+            }
+            return createMemoryLease(port, {
+                key,
+                ownerToken,
+                expiresAt: new Date(0),
+                ttlMs: 1,
+                fencingToken: 0,
+            }, now);
+        },
+        async forceRelease(key) {
+            pruneExpired(key, leases, now);
+            return leases.delete(key);
+        },
+        reset() {
+            leases.clear();
+            nextFencingToken = 1;
+        },
+    };
+    return port;
+}
+/**
+ * Create a provider that contributes an in-memory locks port.
+ */
+export function createMemoryLocksProvider(options = {}) {
+    const { name = "memory-locks", ...locksOptions } = options;
+    return createProvider({
+        name,
+        metadata: {
+            ports: ["locks"],
+            watchers: ["locks"],
+        },
+        setup({ ports }) {
+            const instrumentation = createProviderInstrumentation(ports, {
+                providerName: name,
+                watcher: "locks",
+            });
+            const locks = createMemoryLocks(locksOptions);
+            return {
+                ports: {
+                    locks: instrumentLocks(locks, instrumentation),
+                },
+            };
+        },
+    });
+}
+/**
+ * Convenience helper for any lock port.
+ */
+export function acquireLease(locks, key, options) {
+    return locks.acquire(key, options);
+}
+/**
+ * Convenience helper for any lock port.
+ */
+export function withLease(locks, key, options, fn) {
+    return locks.withLease(key, options, fn);
+}
+function createMemoryLease(port, record, now) {
+    const lease = {
+        key: record.key,
+        ownerToken: record.ownerToken,
+        expiresAt: record.expiresAt,
+        fencingToken: record.fencingToken,
+        async renew(options) {
+            const active = port.leases.get(record.key);
+            if (!active ||
+                active.ownerToken !== record.ownerToken ||
+                active.expiresAt.getTime() <= now().getTime()) {
+                port.leases.delete(record.key);
+                return false;
+            }
+            const ttlMs = options?.ttlMs ?? active.ttlMs;
+            if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+                throw new LeaseOptionsError("Lease ttlMs must be a positive number.");
+            }
+            active.ttlMs = ttlMs;
+            active.expiresAt = new Date(now().getTime() + ttlMs);
+            lease.expiresAt = active.expiresAt;
+            return true;
+        },
+        async release() {
+            const active = port.leases.get(record.key);
+            if (!active || active.ownerToken !== record.ownerToken) {
+                return false;
+            }
+            if (active.expiresAt.getTime() <= now().getTime()) {
+                port.leases.delete(record.key);
+                return false;
+            }
+            return port.leases.delete(record.key);
+        },
+    };
+    return lease;
+}
+function instrumentLocks(locks, instrumentation) {
+    const acquire = async (key, options) => {
+        const startedAt = Date.now();
+        const result = await locks.acquire(key, options);
+        instrumentation.custom({
+            name: "locks.acquire",
+            label: "Lock acquire",
+            summary: result.acquired ? "Lease acquired" : "Lease not acquired",
+            details: {
+                key,
+                acquired: result.acquired,
+                reason: result.acquired ? undefined : result.reason,
+                ttlMs: options.ttlMs,
+                waitMs: options.waitMs ?? 0,
+                durationMs: Date.now() - startedAt,
+            },
+        });
+        return result;
+    };
+    return {
+        acquire,
+        async withLease(key, options, fn) {
+            const result = await acquire(key, options);
+            if (!result.acquired)
+                return undefined;
+            try {
+                return await fn({ lease: result.lease });
+            }
+            finally {
+                await result.lease.release();
+            }
+        },
+        restore(key, ownerToken) {
+            return locks.restore(key, ownerToken);
+        },
+        async forceRelease(key) {
+            const released = await locks.forceRelease(key);
+            instrumentation.custom({
+                name: "locks.forceRelease",
+                label: "Lock force release",
+                summary: released ? "Lease force released" : "Lease not found",
+                details: { key, released },
+            });
+            return released;
+        },
+    };
+}
+function validateAcquireOptions(key, options) {
+    if (!key)
+        throw new LeaseOptionsError("Lease key is required.");
+    if (!Number.isFinite(options.ttlMs) || options.ttlMs <= 0) {
+        throw new LeaseOptionsError("Lease ttlMs must be a positive number.");
+    }
+    if (options.waitMs !== undefined && options.waitMs < 0) {
+        throw new LeaseOptionsError("Lease waitMs must be zero or greater.");
+    }
+    if (options.retryDelayMs !== undefined && options.retryDelayMs <= 0) {
+        throw new LeaseOptionsError("Lease retryDelayMs must be positive.");
+    }
+}
+function pruneExpired(key, leases, now) {
+    const active = leases.get(key);
+    if (active && active.expiresAt.getTime() <= now().getTime()) {
+        leases.delete(key);
+    }
+}
+function createRandomToken() {
+    if (typeof crypto !== "undefined" && "randomUUID" in crypto) {
+        return crypto.randomUUID();
+    }
+    return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+}
+function defaultSleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+//# sourceMappingURL=index.js.map

package/dist/locks/index.js.map

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

package/dist/payments/index.d.ts

@@ -0,0 +1,430 @@
+/**
+ * @beignet/core/payments
+ *
+ * Provider-neutral payments primitives for Beignet applications.
+ */
+/**
+ * Value or promise of that value.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * String metadata attached to provider-owned payment objects.
+ */
+export type PaymentMetadata = Record<string, string>;
+/**
+ * Checkout modes understood by Beignet's provider-neutral payment port.
+ */
+export type PaymentCheckoutMode = "payment" | "subscription";
+/**
+ * Hosted checkout line item.
+ */
+export interface PaymentCheckoutLineItem {
+    /**
+     * Provider price identifier.
+     */
+    priceId: string;
+    /**
+     * Quantity for this price. Defaults to the provider's default behavior.
+     */
+    quantity?: number;
+}
+/**
+ * Input for creating a hosted checkout session.
+ */
+export interface CreateCheckoutSessionInput {
+    /**
+     * One-time payment or subscription checkout.
+     */
+    mode: PaymentCheckoutMode;
+    /**
+     * Line items to include in checkout.
+     */
+    lineItems: readonly PaymentCheckoutLineItem[];
+    /**
+     * URL the provider redirects to after successful checkout.
+     */
+    successUrl: string;
+    /**
+     * URL the provider redirects to when checkout is canceled.
+     */
+    cancelUrl: string;
+    /**
+     * Existing provider customer ID, when known.
+     */
+    customerId?: string;
+    /**
+     * App-owned reference copied into the provider session.
+     */
+    clientReferenceId?: string;
+    /**
+     * Provider metadata.
+     */
+    metadata?: PaymentMetadata;
+    /**
+     * Provider idempotency key for this external call.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Hosted checkout session returned by a payment provider.
+ */
+export interface CheckoutSession {
+    /**
+     * Provider session ID.
+     */
+    id: string;
+    /**
+     * Provider name.
+     */
+    provider: string;
+    /**
+     * Checkout mode.
+     */
+    mode: PaymentCheckoutMode;
+    /**
+     * Hosted checkout URL, when the provider returns one.
+     */
+    url?: string;
+    /**
+     * Client secret, when the provider supports embedded checkout.
+     */
+    clientSecret?: string;
+    /**
+     * Provider customer ID, when known.
+     */
+    customerId?: string;
+    /**
+     * Provider status, when known.
+     */
+    status?: string;
+    /**
+     * Provider metadata.
+     */
+    metadata?: PaymentMetadata;
+    /**
+     * Raw provider response for app-owned escape hatches.
+     */
+    raw?: unknown;
+}
+/**
+ * Input for creating a billing portal session.
+ */
+export interface CreateBillingPortalSessionInput {
+    /**
+     * Provider customer ID.
+     */
+    customerId: string;
+    /**
+     * URL the provider redirects to after leaving the portal.
+     */
+    returnUrl: string;
+    /**
+     * Provider idempotency key for this external call.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Billing portal session returned by a payment provider.
+ */
+export interface BillingPortalSession {
+    /**
+     * Provider session ID.
+     */
+    id: string;
+    /**
+     * Provider name.
+     */
+    provider: string;
+    /**
+     * Hosted portal URL.
+     */
+    url: string;
+    /**
+     * Provider customer ID.
+     */
+    customerId: string;
+    /**
+     * Raw provider response for app-owned escape hatches.
+     */
+    raw?: unknown;
+}
+/**
+ * Refund reasons common to hosted payment providers.
+ */
+export type PaymentRefundReason = "duplicate" | "fraudulent" | "requested_by_customer";
+/**
+ * Input for creating a refund.
+ */
+export interface CreateRefundInput {
+    /**
+     * Provider payment ID, such as a payment intent ID.
+     */
+    paymentId: string;
+    /**
+     * Amount in the provider's smallest currency unit. Omit for a full refund.
+     */
+    amount?: number;
+    /**
+     * Reason for the refund.
+     */
+    reason?: PaymentRefundReason;
+    /**
+     * Provider metadata.
+     */
+    metadata?: PaymentMetadata;
+    /**
+     * Provider idempotency key for this external call.
+     */
+    idempotencyKey?: string;
+}
+/**
+ * Refund returned by a payment provider.
+ */
+export interface Refund {
+    /**
+     * Provider refund ID.
+     */
+    id: string;
+    /**
+     * Provider name.
+     */
+    provider: string;
+    /**
+     * Provider payment ID that was refunded.
+     */
+    paymentId: string;
+    /**
+     * Refunded amount in the provider's smallest currency unit, when known.
+     */
+    amount?: number;
+    /**
+     * Currency code, when known.
+     */
+    currency?: string;
+    /**
+     * Provider refund status, when known.
+     */
+    status?: string;
+    /**
+     * Provider metadata.
+     */
+    metadata?: PaymentMetadata;
+    /**
+     * Raw provider response for app-owned escape hatches.
+     */
+    raw?: unknown;
+}
+/**
+ * Raw webhook payload accepted by payment providers.
+ */
+export type PaymentWebhookRawBody = string | Uint8Array | ArrayBuffer;
+/**
+ * Input for verifying and parsing a provider webhook.
+ */
+export interface VerifyPaymentWebhookInput {
+    /**
+     * Raw request body. Do not pass a parsed JSON body.
+     */
+    rawBody: PaymentWebhookRawBody;
+    /**
+     * Provider signature header value.
+     */
+    signature: string;
+}
+/**
+ * Normalized provider webhook event.
+ */
+export interface PaymentWebhookEvent {
+    /**
+     * Provider event ID.
+     */
+    id: string;
+    /**
+     * Provider event type, such as "checkout.session.completed".
+     */
+    type: string;
+    /**
+     * Provider name.
+     */
+    provider: string;
+    /**
+     * Event creation time, when known.
+     */
+    createdAt?: Date;
+    /**
+     * Whether the event came from live mode, when the provider exposes it.
+     */
+    livemode?: boolean;
+    /**
+     * Provider event data object.
+     */
+    data: unknown;
+    /**
+     * Raw provider event for app-owned escape hatches.
+     */
+    raw?: unknown;
+}
+/**
+ * App-facing payments port.
+ *
+ * Implement this with hosted payment providers such as Stripe. Application
+ * billing logic should depend on this interface instead of provider SDKs.
+ */
+export interface PaymentsPort {
+    /**
+     * Create a hosted checkout session.
+     */
+    createCheckoutSession(input: CreateCheckoutSessionInput): Promise<CheckoutSession>;
+    /**
+     * Create a hosted billing portal session.
+     */
+    createBillingPortalSession(input: CreateBillingPortalSessionInput): Promise<BillingPortalSession>;
+    /**
+     * Create a refund.
+     */
+    createRefund(input: CreateRefundInput): Promise<Refund>;
+    /**
+     * Verify and parse a provider webhook.
+     */
+    verifyWebhook(input: VerifyPaymentWebhookInput): Promise<PaymentWebhookEvent>;
+}
+/**
+ * Error thrown by payment helpers and provider adapters.
+ */
+export declare class PaymentProviderError extends Error {
+    /**
+     * Provider name when known.
+     */
+    readonly provider?: string;
+    /**
+     * Operation that failed.
+     */
+    readonly operation: string;
+    /**
+     * Provider error code when known.
+     */
+    readonly code?: string;
+    /**
+     * Original provider error when available.
+     */
+    readonly cause?: unknown;
+    constructor(args: {
+        provider?: string;
+        operation: string;
+        message: string;
+        code?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * Captured checkout session created by the memory payments adapter.
+ */
+export type MemoryCheckoutSession = CheckoutSession & {
+    input: CreateCheckoutSessionInput;
+    createdAt: Date;
+};
+/**
+ * Captured billing portal session created by the memory payments adapter.
+ */
+export type MemoryBillingPortalSession = BillingPortalSession & {
+    input: CreateBillingPortalSessionInput;
+    createdAt: Date;
+};
+/**
+ * Captured refund created by the memory payments adapter.
+ */
+export type MemoryRefund = Refund & {
+    input: CreateRefundInput;
+    createdAt: Date;
+};
+/**
+ * In-memory payments port for tests and local examples.
+ */
+export interface MemoryPaymentsPort extends PaymentsPort {
+    /**
+     * Captured checkout sessions.
+     */
+    readonly checkoutSessions: readonly MemoryCheckoutSession[];
+    /**
+     * Captured billing portal sessions.
+     */
+    readonly billingPortalSessions: readonly MemoryBillingPortalSession[];
+    /**
+     * Captured refunds.
+     */
+    readonly refunds: readonly MemoryRefund[];
+    /**
+     * Webhook events that were verified by the memory adapter.
+     */
+    readonly webhookEvents: readonly PaymentWebhookEvent[];
+    /**
+     * Queue a webhook event to be returned by the next `verifyWebhook(...)` call.
+     */
+    queueWebhookEvent(event: PaymentWebhookEvent): void;
+    /**
+     * Clear captured state.
+     */
+    clear(): void;
+}
+/**
+ * Options for `createMemoryPayments(...)`.
+ */
+export interface CreateMemoryPaymentsOptions {
+    /**
+     * Clock used for captured payment objects.
+     */
+    now?: () => Date;
+    /**
+     * ID factory used for captured payment objects.
+     */
+    id?: (prefix: string) => string;
+    /**
+     * Observer called after a checkout session is created.
+     */
+    onCheckoutSessionCreated?: (session: MemoryCheckoutSession) => MaybePromise<void>;
+    /**
+     * Observer called after a billing portal session is created.
+     */
+    onBillingPortalSessionCreated?: (session: MemoryBillingPortalSession) => MaybePromise<void>;
+    /**
+     * Observer called after a refund is created.
+     */
+    onRefundCreated?: (refund: MemoryRefund) => MaybePromise<void>;
+    /**
+     * Observer called after a webhook event is verified.
+     */
+    onWebhookVerified?: (event: PaymentWebhookEvent) => MaybePromise<void>;
+}
+/**
+ * Create an in-memory payments port for tests, local development, and
+ * examples.
+ *
+ * The memory adapter does not contact a payment provider or validate webhook
+ * signatures. Queue webhook events explicitly with `queueWebhookEvent(...)`.
+ */
+export declare function createMemoryPayments(options?: CreateMemoryPaymentsOptions): MemoryPaymentsPort;
+/**
+ * Options for the memory payments provider.
+ */
+export interface MemoryPaymentsProviderOptions extends CreateMemoryPaymentsOptions {
+    /**
+     * Provider name. Defaults to "memory-payments".
+     */
+    name?: string;
+}
+/**
+ * Ports contributed by the memory payments provider.
+ */
+export interface MemoryPaymentsProviderPorts {
+    /**
+     * Beignet payments port.
+     */
+    payments: PaymentsPort;
+}
+/**
+ * Create a provider that contributes an in-memory payments port.
+ */
+export declare function createMemoryPaymentsProvider(options?: MemoryPaymentsProviderOptions): import("../providers/provider.js").ServiceProvider<unknown, import("@standard-schema/spec").StandardSchemaV1<void, void>, {
+    payments: PaymentsPort;
+}, unknown, void>;
+//# sourceMappingURL=index.d.ts.map

package/dist/payments/index.d.ts.map

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