@digimuza/saas-core 0.0.2

package/dist/authorization/service.d.ts

@@ -0,0 +1,92 @@
+import type { CoreDatabase } from "../db/types.ts";
+import { type CoreEventPublisher } from "../events/publisher.ts";
+import type { Role } from "../db/schema/index.ts";
+import type { WorkspaceContext } from "../workspaces/context.ts";
+/**
+ * A permission identifier such as `"projects.create"`.
+ *
+ * Applications define their own vocabulary. Declare it with
+ * {@link definePermissions} to get a union type and autocompletion; the core
+ * itself accepts any string, because it cannot know a product's permissions.
+ */
+export type PermissionKey = string;
+export interface PermissionDefinition {
+    readonly key: string;
+    readonly description?: string;
+}
+export interface CreateRoleInput {
+    readonly key: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly isDefault?: boolean;
+    readonly permissions?: readonly PermissionKey[];
+}
+export interface AuthorizationService {
+    /**
+     * Register the application's permission vocabulary.
+     *
+     * Idempotent, so it is safe to call on every boot or from a migration step.
+     * Permissions must exist before a role can be granted them.
+     */
+    registerPermissions(definitions: readonly PermissionDefinition[]): Promise<void>;
+    /** Every permission the user holds in this workspace: the union across their roles. */
+    getEffectivePermissions(context: WorkspaceContext): Promise<Set<PermissionKey>>;
+    /** Whether the user holds `permission` in this workspace. */
+    can(context: WorkspaceContext, permission: PermissionKey): Promise<boolean>;
+    /** True only when the user holds *every* listed permission. */
+    canAll(context: WorkspaceContext, required: readonly PermissionKey[]): Promise<boolean>;
+    /** True when the user holds *any* of the listed permissions. */
+    canAny(context: WorkspaceContext, required: readonly PermissionKey[]): Promise<boolean>;
+    /** As {@link can}, but throws {@link ForbiddenError}. */
+    require(context: WorkspaceContext, permission: PermissionKey): Promise<void>;
+    /**
+     * Whether the user holds a role with this key in this workspace.
+     *
+     * Prefer permissions. Role checks couple application logic to the role
+     * structure, so renaming or restructuring roles silently changes behaviour.
+     */
+    hasRole(context: WorkspaceContext, roleKey: string): Promise<boolean>;
+    /** The user's roles in this workspace. */
+    getRoles(context: WorkspaceContext): Promise<Role[]>;
+    readonly roles: {
+        list(context: WorkspaceContext): Promise<Role[]>;
+        create(context: WorkspaceContext, input: CreateRoleInput): Promise<Role>;
+        /** Replace a role's permission set. */
+        setPermissions(context: WorkspaceContext, roleId: string, keys: readonly PermissionKey[]): Promise<void>;
+        /** Delete a custom role. System roles are protected. */
+        delete(context: WorkspaceContext, roleId: string): Promise<void>;
+        assign(context: WorkspaceContext, input: {
+            userId: string;
+            roleId: string;
+        }): Promise<void>;
+        unassign(context: WorkspaceContext, input: {
+            userId: string;
+            roleId: string;
+        }): Promise<void>;
+    };
+}
+export interface AuthorizationServiceDeps {
+    readonly db: CoreDatabase;
+    /** Optional event publisher. Omit it and the service emits nothing. */
+    readonly events?: CoreEventPublisher;
+}
+export declare function createAuthorizationService(deps: AuthorizationServiceDeps): AuthorizationService;
+/**
+ * Declare an application's permission vocabulary and get a union type for it.
+ *
+ * ```ts
+ * export const PERMISSIONS = definePermissions([
+ *   "projects.read",
+ *   "projects.create",
+ * ] as const);
+ *
+ * type AppPermission = (typeof PERMISSIONS)[number]; // "projects.read" | "projects.create"
+ * ```
+ *
+ * Purely a typing helper — it performs no I/O. Pass the same list to
+ * `registerPermissions()` to persist it.
+ */
+export declare function definePermissions<const T extends readonly string[]>(keys: T): T;
+/** Look up which roles in a workspace carry a given permission. */
+export declare function findRolesWithPermission(db: CoreDatabase, workspaceId: string, permission: PermissionKey): Promise<Role[]>;
+//# sourceMappingURL=service.d.ts.map

package/dist/authorization/service.d.ts.map

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

package/dist/authorization/service.js

@@ -0,0 +1,254 @@
+import { and, eq, inArray } from "drizzle-orm";
+import { ForbiddenError, NotFoundError } from "../errors.js";
+import { isForeignKeyViolation } from "../db/errors.js";
+import { permissions as permissionsTable, rolePermissions, roles, workspaceMemberRoles, } from "../db/schema/index.js";
+import { EventOutbox } from "../events/publisher.js";
+export function createAuthorizationService(deps) {
+    const outbox = () => new EventOutbox(deps.events);
+    /**
+     * Confirm a role belongs to the caller's workspace before it is used.
+     *
+     * The database rejects cross-workspace *grants* outright, but reads and
+     * deletes need this check so a role id from another tenant cannot be probed
+     * or modified.
+     */
+    async function requireOwnRole(context, roleId) {
+        const rows = await deps.db
+            .select()
+            .from(roles)
+            .where(and(eq(roles.id, roleId), eq(roles.workspaceId, context.workspaceId)))
+            .limit(1);
+        const role = rows[0];
+        if (role === undefined) {
+            throw new NotFoundError("Role not found.");
+        }
+        return role;
+    }
+    const roleAdmin = {
+        async list(context) {
+            return deps.db.select().from(roles).where(eq(roles.workspaceId, context.workspaceId));
+        },
+        async create(context, input) {
+            return deps.db.transaction(async (tx) => {
+                const [role] = await tx
+                    .insert(roles)
+                    .values({
+                    workspaceId: context.workspaceId,
+                    key: input.key,
+                    name: input.name,
+                    description: input.description ?? null,
+                    isDefault: input.isDefault ?? false,
+                    isSystem: false,
+                })
+                    .returning();
+                if (input.permissions !== undefined && input.permissions.length > 0) {
+                    await tx.insert(rolePermissions).values(input.permissions.map((permissionKey) => ({
+                        roleId: role.id,
+                        permissionKey,
+                    })));
+                }
+                return role;
+            });
+        },
+        async setPermissions(context, roleId, keys) {
+            await requireOwnRole(context, roleId);
+            await deps.db.transaction(async (tx) => {
+                await tx.delete(rolePermissions).where(eq(rolePermissions.roleId, roleId));
+                if (keys.length > 0) {
+                    await tx
+                        .insert(rolePermissions)
+                        .values(keys.map((permissionKey) => ({ roleId, permissionKey })));
+                }
+            });
+        },
+        async delete(context, roleId) {
+            const role = await requireOwnRole(context, roleId);
+            /**
+             * System roles are created with the workspace and other code assumes they
+             * exist — deleting `admin` would leave nobody able to administer it.
+             */
+            if (role.isSystem) {
+                throw new ForbiddenError("System roles cannot be deleted.");
+            }
+            await deps.db.delete(roles).where(eq(roles.id, roleId));
+        },
+        async assign(context, input) {
+            const events = outbox();
+            try {
+                const granted = await deps.db.transaction(async (tx) => {
+                    const inserted = await tx
+                        .insert(workspaceMemberRoles)
+                        .values({
+                        workspaceId: context.workspaceId,
+                        userId: input.userId,
+                        roleId: input.roleId,
+                    })
+                        .onConflictDoNothing()
+                        .returning({ roleId: workspaceMemberRoles.roleId });
+                    // Nothing inserted means the role was already held; not a change, so
+                    // no event. Re-announcing it would make consumers act twice.
+                    if (inserted.length === 0) {
+                        return false;
+                    }
+                    await events.record({
+                        type: "workspace.member.role.updated",
+                        workspaceId: context.workspaceId,
+                        actorId: context.userId,
+                        data: { userId: input.userId, roleId: input.roleId, action: "assigned" },
+                    }, tx);
+                    return true;
+                });
+                if (granted) {
+                    await events.flush();
+                }
+            }
+            catch (error) {
+                /**
+                 * Both failures are the database enforcing tenancy: the role belongs to
+                 * another workspace, or the user is not a member of this one. Neither
+                 * should be reported as an unexpected error.
+                 */
+                if (isForeignKeyViolation(error, "workspace_member_roles_role_fk") ||
+                    isForeignKeyViolation(error, "workspace_member_roles_member_fk")) {
+                    throw new NotFoundError("Role or workspace member not found.");
+                }
+                throw error;
+            }
+        },
+        async unassign(context, input) {
+            const removed = await deps.db
+                .delete(workspaceMemberRoles)
+                .where(and(eq(workspaceMemberRoles.workspaceId, context.workspaceId), eq(workspaceMemberRoles.userId, input.userId), eq(workspaceMemberRoles.roleId, input.roleId)))
+                .returning({ roleId: workspaceMemberRoles.roleId });
+            if (removed.length === 0) {
+                throw new NotFoundError("Role assignment not found.");
+            }
+            const events = outbox();
+            await events.record({
+                type: "workspace.member.role.updated",
+                workspaceId: context.workspaceId,
+                actorId: context.userId,
+                data: { userId: input.userId, roleId: input.roleId, action: "unassigned" },
+            }, deps.db);
+            await events.flush();
+        },
+    };
+    const service = {
+        async registerPermissions(definitions) {
+            if (definitions.length === 0) {
+                return;
+            }
+            await deps.db
+                .insert(permissionsTable)
+                .values(definitions.map((definition) => ({
+                key: definition.key,
+                description: definition.description ?? null,
+            })))
+                .onConflictDoUpdate({
+                target: permissionsTable.key,
+                set: { updatedAt: new Date() },
+            });
+        },
+        async getEffectivePermissions(context) {
+            /**
+             * A single join from the member's grants through their roles to the
+             * permissions those roles carry. The union is inherent: `select distinct`
+             * over all matching rows, so holding several roles simply widens the set.
+             *
+             * Both halves of the join to `roles` are constrained by workspace, so a
+             * stale grant could not contribute another tenant's permissions.
+             */
+            const rows = await deps.db
+                .selectDistinct({ key: rolePermissions.permissionKey })
+                .from(workspaceMemberRoles)
+                .innerJoin(roles, and(eq(roles.id, workspaceMemberRoles.roleId), eq(roles.workspaceId, workspaceMemberRoles.workspaceId)))
+                .innerJoin(rolePermissions, eq(rolePermissions.roleId, roles.id))
+                .where(and(eq(workspaceMemberRoles.workspaceId, context.workspaceId), eq(workspaceMemberRoles.userId, context.userId)));
+            return new Set(rows.map((row) => row.key));
+        },
+        async can(context, permission) {
+            const held = await service.getEffectivePermissions(context);
+            return held.has(permission);
+        },
+        async canAll(context, required) {
+            if (required.length === 0) {
+                return true;
+            }
+            const held = await service.getEffectivePermissions(context);
+            return required.every((permission) => held.has(permission));
+        },
+        async canAny(context, required) {
+            if (required.length === 0) {
+                return false;
+            }
+            const held = await service.getEffectivePermissions(context);
+            return required.some((permission) => held.has(permission));
+        },
+        async require(context, permission) {
+            if (!(await service.can(context, permission))) {
+                throw new ForbiddenError(`Missing permission "${permission}".`, { permission });
+            }
+        },
+        async hasRole(context, roleKey) {
+            const rows = await deps.db
+                .select({ id: roles.id })
+                .from(workspaceMemberRoles)
+                .innerJoin(roles, and(eq(roles.id, workspaceMemberRoles.roleId), eq(roles.workspaceId, workspaceMemberRoles.workspaceId)))
+                .where(and(eq(workspaceMemberRoles.workspaceId, context.workspaceId), eq(workspaceMemberRoles.userId, context.userId), eq(roles.key, roleKey)))
+                .limit(1);
+            return rows.length > 0;
+        },
+        async getRoles(context) {
+            return deps.db
+                .select({
+                id: roles.id,
+                workspaceId: roles.workspaceId,
+                key: roles.key,
+                name: roles.name,
+                description: roles.description,
+                isSystem: roles.isSystem,
+                isDefault: roles.isDefault,
+                createdAt: roles.createdAt,
+                updatedAt: roles.updatedAt,
+            })
+                .from(workspaceMemberRoles)
+                .innerJoin(roles, and(eq(roles.id, workspaceMemberRoles.roleId), eq(roles.workspaceId, workspaceMemberRoles.workspaceId)))
+                .where(and(eq(workspaceMemberRoles.workspaceId, context.workspaceId), eq(workspaceMemberRoles.userId, context.userId)));
+        },
+        roles: roleAdmin,
+    };
+    return service;
+}
+/**
+ * Declare an application's permission vocabulary and get a union type for it.
+ *
+ * ```ts
+ * export const PERMISSIONS = definePermissions([
+ *   "projects.read",
+ *   "projects.create",
+ * ] as const);
+ *
+ * type AppPermission = (typeof PERMISSIONS)[number]; // "projects.read" | "projects.create"
+ * ```
+ *
+ * Purely a typing helper — it performs no I/O. Pass the same list to
+ * `registerPermissions()` to persist it.
+ */
+export function definePermissions(keys) {
+    return keys;
+}
+/** Look up which roles in a workspace carry a given permission. */
+export async function findRolesWithPermission(db, workspaceId, permission) {
+    const grantedRoleIds = await db
+        .select({ roleId: rolePermissions.roleId })
+        .from(rolePermissions)
+        .where(eq(rolePermissions.permissionKey, permission));
+    if (grantedRoleIds.length === 0) {
+        return [];
+    }
+    return db
+        .select()
+        .from(roles)
+        .where(and(eq(roles.workspaceId, workspaceId), inArray(roles.id, grantedRoleIds.map((row) => row.roleId))));
+}
+//# sourceMappingURL=service.js.map

package/dist/authorization/service.js.map

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

package/dist/billing/index.d.ts

@@ -0,0 +1,16 @@
+import { type BillingService } from "./service.ts";
+import type { BillingProvider } from "./provider.ts";
+export { assertEntitlementDefinitions, countFailedBillingEvents, createBillingService, InvalidWebhookSignatureError, type BillingService, type BillingServiceDeps, type CreateCheckoutOptions, type EntitlementDefinition, type SubscriptionWithPlan, type UpsertPlanInput, type WebhookOutcome, type WebhookRequest, } from "./service.ts";
+export type { BillingProvider, CancelSubscriptionInput, CheckoutSession, CreateCheckoutInput, CreateCustomerInput, PortalInput, ProviderCustomer, ProviderSubscriptionState, ProviderWebhookEvent, WebhookVerificationInput, } from "./provider.ts";
+export { createRevolutProvider, mapRevolutStatus, verifyRevolutSignature, type RevolutAdapterOptions, } from "./revolut.ts";
+/** The Revolut provider, built from the `billing` configuration section. */
+export declare function createConfiguredProvider(): BillingProvider;
+/**
+ * Default service, bound to configuration and the Revolut adapter.
+ *
+ * Both dependencies are getters, so the `billing` and `database` configuration
+ * sections resolve on first use rather than at import — importing this module
+ * does not require Revolut credentials.
+ */
+export declare const billing: BillingService;
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAeA,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,cAAc,CAAC;AAEzE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AAErD,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,4BAA4B,EAC5B,KAAK,cAAc,EACnB,KAAK,kBAAkB,EACvB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,oBAAoB,EACzB,KAAK,eAAe,EACpB,KAAK,cAAc,EACnB,KAAK,cAAc,GACpB,MAAM,cAAc,CAAC;AAEtB,YAAY,EACV,eAAe,EACf,uBAAuB,EACvB,eAAe,EACf,mBAAmB,EACnB,mBAAmB,EACnB,WAAW,EACX,gBAAgB,EAChB,yBAAyB,EACzB,oBAAoB,EACpB,wBAAwB,GACzB,MAAM,eAAe,CAAC;AAEvB,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,sBAAsB,EACtB,KAAK,qBAAqB,GAC3B,MAAM,cAAc,CAAC;AAEtB,4EAA4E;AAC5E,wBAAgB,wBAAwB,IAAI,eAAe,CAO1D;AAID;;;;;;GAMG;AACH,eAAO,MAAM,OAAO,EAAE,cASpB,CAAC"}

package/dist/billing/index.js

@@ -0,0 +1,47 @@
+/**
+ * Public billing surface: `@digimuza/saas-core/billing`. Server-only.
+ *
+ * Provider-independent by construction: everything above {@link BillingProvider}
+ * is generic, so adopting a second payment provider means writing an adapter.
+ * Application code must never inspect a plan name to decide what a customer may
+ * do — ask `@digimuza/saas-core/entitlements` instead.
+ *
+ * Billing state changes only from verified webhook events, never from the
+ * browser's return trip after checkout: that redirect is attacker-controllable
+ * and proves nothing about payment.
+ */
+import { config } from "../config/index.js";
+import { getDatabase } from "../db/client.js";
+import { events as coreEventsService } from "../events/index.js";
+import { createBillingService } from "./service.js";
+import { createRevolutProvider } from "./revolut.js";
+export { assertEntitlementDefinitions, countFailedBillingEvents, createBillingService, InvalidWebhookSignatureError, } from "./service.js";
+export { createRevolutProvider, mapRevolutStatus, verifyRevolutSignature, } from "./revolut.js";
+/** The Revolut provider, built from the `billing` configuration section. */
+export function createConfiguredProvider() {
+    const billing = config.billing;
+    return createRevolutProvider({
+        apiKey: billing.apiKey,
+        webhookSecret: billing.webhookSecret,
+        apiUrl: billing.apiUrl,
+    });
+}
+let configuredProvider;
+/**
+ * Default service, bound to configuration and the Revolut adapter.
+ *
+ * Both dependencies are getters, so the `billing` and `database` configuration
+ * sections resolve on first use rather than at import — importing this module
+ * does not require Revolut credentials.
+ */
+export const billing = createBillingService({
+    get db() {
+        return getDatabase();
+    },
+    get provider() {
+        configuredProvider ??= createConfiguredProvider();
+        return configuredProvider;
+    },
+    events: coreEventsService,
+});
+//# sourceMappingURL=index.js.map

package/dist/billing/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/billing/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AAC5C,OAAO,EAAE,WAAW,EAAE,MAAM,iBAAiB,CAAC;AAC9C,OAAO,EAAE,MAAM,IAAI,iBAAiB,EAAE,MAAM,oBAAoB,CAAC;AACjE,OAAO,EAAE,oBAAoB,EAAuB,MAAM,cAAc,CAAC;AACzE,OAAO,EAAE,qBAAqB,EAAE,MAAM,cAAc,CAAC;AAGrD,OAAO,EACL,4BAA4B,EAC5B,wBAAwB,EACxB,oBAAoB,EACpB,4BAA4B,GAS7B,MAAM,cAAc,CAAC;AAetB,OAAO,EACL,qBAAqB,EACrB,gBAAgB,EAChB,sBAAsB,GAEvB,MAAM,cAAc,CAAC;AAEtB,4EAA4E;AAC5E,MAAM,UAAU,wBAAwB;IACtC,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC;IAC/B,OAAO,qBAAqB,CAAC;QAC3B,MAAM,EAAE,OAAO,CAAC,MAAM;QACtB,aAAa,EAAE,OAAO,CAAC,aAAa;QACpC,MAAM,EAAE,OAAO,CAAC,MAAM;KACvB,CAAC,CAAC;AACL,CAAC;AAED,IAAI,kBAA+C,CAAC;AAEpD;;;;;;GAMG;AACH,MAAM,CAAC,MAAM,OAAO,GAAmB,oBAAoB,CAAC;IAC1D,IAAI,EAAE;QACJ,OAAO,WAAW,EAAE,CAAC;IACvB,CAAC;IACD,IAAI,QAAQ;QACV,kBAAkB,KAAK,wBAAwB,EAAE,CAAC;QAClD,OAAO,kBAAkB,CAAC;IAC5B,CAAC;IACD,MAAM,EAAE,iBAAiB;CAC1B,CAAC,CAAC"}

package/dist/billing/provider.d.ts

@@ -0,0 +1,114 @@
+import type { Plan, SubscriptionStatus } from "../db/schema/index.ts";
+/**
+ * The seam between the core and a payment provider.
+ *
+ * Everything above this interface is provider-independent, so adopting a second
+ * provider means writing an adapter rather than touching the schema, the
+ * services or any application code.
+ *
+ * Not every provider offers every capability. `cancelSubscription` and
+ * `getPortalUrl` are optional: Revolut has no hosted customer portal and no
+ * server-side subscription object to cancel, and pretending otherwise would mean
+ * shipping methods that silently do nothing. The billing service handles their
+ * absence explicitly.
+ */
+export interface BillingProvider {
+    /** Stored on every row this provider produces, e.g. `"revolut"`. */
+    readonly name: string;
+    createCustomer(input: CreateCustomerInput): Promise<ProviderCustomer>;
+    createCheckout(input: CreateCheckoutInput): Promise<CheckoutSession>;
+    /** Omit when the provider has no server-side subscription to cancel. */
+    cancelSubscription?(input: CancelSubscriptionInput): Promise<void>;
+    /** Omit when the provider has no hosted billing portal. */
+    getPortalUrl?(input: PortalInput): Promise<string>;
+    /**
+     * Verify a webhook's authenticity.
+     *
+     * Must be given the **raw** request body. Parsing and re-serialising JSON
+     * changes key order and whitespace, which invalidates the signature — so a
+     * route handler has to read the body as text before touching it.
+     */
+    verifyWebhook(input: WebhookVerificationInput): boolean;
+    /** Translate a verified webhook body into a provider-independent event. */
+    parseWebhookEvent(rawBody: string): ProviderWebhookEvent;
+}
+export interface ProviderCustomer {
+    readonly providerCustomerId: string;
+}
+export interface CreateCustomerInput {
+    readonly workspaceId: string;
+    readonly workspaceName: string;
+    readonly email?: string;
+}
+export interface CreateCheckoutInput {
+    readonly workspaceId: string;
+    readonly providerCustomerId: string;
+    readonly plan: Plan;
+    readonly successUrl: string;
+    readonly cancelUrl: string;
+    readonly quantity?: number;
+    /** Echoed back on webhooks, where the provider supports it. */
+    readonly metadata?: Record<string, string>;
+}
+export interface CheckoutSession {
+    /** Where to send the customer to pay. */
+    readonly url: string;
+    readonly providerCheckoutId?: string;
+}
+export interface CancelSubscriptionInput {
+    readonly providerSubscriptionId: string;
+    /** Cancel at the end of the paid period rather than immediately. */
+    readonly atPeriodEnd: boolean;
+}
+export interface PortalInput {
+    readonly providerCustomerId: string;
+    readonly returnUrl: string;
+}
+export interface WebhookVerificationInput {
+    /** The request body exactly as received, before any parsing. */
+    readonly rawBody: string;
+    readonly signature: string;
+    /** Provider timestamp header, used for replay protection. */
+    readonly timestamp?: string;
+}
+/**
+ * Normalised subscription state carried by a webhook.
+ *
+ * The adapter maps the provider's status vocabulary onto
+ * {@link SubscriptionStatus}, so application queries never see provider strings.
+ *
+ * Date fields must be real `Date` instances. Providers send them as ISO strings,
+ * and converting them is the adapter's job — passing a string through would fail
+ * deep inside the database driver with an error that names neither the field nor
+ * the adapter.
+ */
+export interface ProviderSubscriptionState {
+    readonly providerSubscriptionId: string;
+    readonly providerCustomerId: string;
+    /**
+     * Resolve the plan by `plans.provider_price_id` — for providers with a price
+     * catalogue (Stripe, Paddle).
+     */
+    readonly providerPriceId?: string;
+    /**
+     * Resolve the plan by `plans.key` — for providers with no catalogue, where the
+     * plan is carried in a reference we set when creating the payment. Consulted
+     * only when {@link providerPriceId} is absent.
+     */
+    readonly planKey?: string;
+    readonly status: SubscriptionStatus;
+    readonly currentPeriodStart?: Date;
+    readonly currentPeriodEnd?: Date;
+    readonly cancelAtPeriodEnd?: boolean;
+    readonly canceledAt?: Date;
+    readonly trialEndsAt?: Date;
+}
+export interface ProviderWebhookEvent {
+    /** Provider's own event id. The idempotency key for ingestion. */
+    readonly providerEventId: string;
+    readonly type: string;
+    readonly payload: unknown;
+    /** Present when the event changes subscription state. */
+    readonly subscription?: ProviderSubscriptionState;
+}
+//# sourceMappingURL=provider.d.ts.map

package/dist/billing/provider.d.ts.map

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

package/dist/billing/provider.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=provider.js.map

package/dist/billing/provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"provider.js","sourceRoot":"","sources":["../../src/billing/provider.ts"],"names":[],"mappings":""}

package/dist/billing/revolut.d.ts

@@ -0,0 +1,68 @@
+import type { SubscriptionStatus } from "../db/schema/index.ts";
+import type { BillingProvider } from "./provider.ts";
+/**
+ * Revolut Merchant API adapter.
+ *
+ * ## Capability boundaries
+ *
+ * Revolut Merchant is an order-and-payment API, not a subscription platform. It
+ * has no hosted customer portal and no server-side subscription object, so
+ * `getPortalUrl` and `cancelSubscription` are deliberately absent from this
+ * adapter rather than stubbed. Recurring charges on Revolut are
+ * merchant-initiated: the core owns subscription state and drives the charges,
+ * and cancellation is therefore a local state change.
+ *
+ * ## Verification status
+ *
+ * The webhook signature scheme is fully implemented and unit-tested against the
+ * documented algorithm. The HTTP calls are written against the documented
+ * endpoints but have **not** been exercised against live Revolut credentials.
+ * Treat `createCustomer` and `createCheckout` as unverified until they have run
+ * against a sandbox account.
+ */
+export interface RevolutAdapterOptions {
+    readonly apiKey: string;
+    readonly webhookSecret: string;
+    /** Base URL. Sandbox differs from production. */
+    readonly apiUrl: string;
+    /**
+     * Reject webhooks whose timestamp is older than this, in seconds.
+     *
+     * Replay protection: a signature stays valid forever, so without a freshness
+     * window a captured request could be replayed indefinitely.
+     */
+    readonly timestampToleranceSeconds?: number;
+    /** Injected for tests. Defaults to the global `fetch`. */
+    readonly fetchImpl?: typeof fetch;
+    /** Injected for tests, so signature freshness is deterministic. */
+    readonly now?: () => number;
+}
+/**
+ * Map Revolut order/payment states onto the core's vocabulary.
+ *
+ * Unknown states deliberately fall through to `incomplete` rather than `active`:
+ * treating an unrecognised state as paid would grant entitlements the customer
+ * may not have.
+ */
+export declare function mapRevolutStatus(state: string): SubscriptionStatus;
+/**
+ * Verify a Revolut webhook signature.
+ *
+ * Revolut signs `v1.{timestamp}.{raw body}` with HMAC-SHA256 under the webhook
+ * signing secret, and sends the result as `Revolut-Signature: v1=<hex>`. During
+ * secret rotation the header may carry several comma-separated signatures, any
+ * one of which may match.
+ *
+ * Exported separately from the adapter so a route handler can verify without
+ * constructing API credentials it does not need.
+ */
+export declare function verifyRevolutSignature(input: {
+    rawBody: string;
+    signature: string;
+    timestamp: string;
+    secret: string;
+    toleranceSeconds?: number;
+    now?: () => number;
+}): boolean;
+export declare function createRevolutProvider(options: RevolutAdapterOptions): BillingProvider;
+//# sourceMappingURL=revolut.d.ts.map

package/dist/billing/revolut.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"revolut.d.ts","sourceRoot":"","sources":["../../src/billing/revolut.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,uBAAuB,CAAC;AAChE,OAAO,KAAK,EACV,eAAe,EAOhB,MAAM,eAAe,CAAC;AAEvB;;;;;;;;;;;;;;;;;;;GAmBG;AACH,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,iDAAiD;IACjD,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB;;;;;OAKG;IACH,QAAQ,CAAC,yBAAyB,CAAC,EAAE,MAAM,CAAC;IAC5C,0DAA0D;IAC1D,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IAClC,mEAAmE;IACnE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CAC7B;AAID;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,kBAAkB,CAmBlE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,sBAAsB,CAAC,KAAK,EAAE;IAC5C,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;CACpB,GAAG,OAAO,CAqCV;AAYD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,qBAAqB,GAAG,eAAe,CAiIrF"}