@openbilling/core 0.1.0

package/LICENSE

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

package/dist/index.cjs

@@ -0,0 +1,60 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  Payment: () => Payment,
+  Provider: () => Provider,
+  Subscription: () => Subscription,
+  Webhook: () => Webhook,
+  createBilling: () => createBilling
+});
+module.exports = __toCommonJS(index_exports);
+var Provider = {
+  /** Stripe provider adapter name. */
+  Stripe: "stripe",
+  /** Dodo Payments provider adapter name. */
+  Dodo: "dodo"
+};
+var Subscription = {
+  /** A subscription became active. */
+  Active: "subscription.active",
+  /** A subscription was cancelled. */
+  Cancelled: "subscription.cancelled"
+};
+var Payment = {
+  /** A payment completed successfully. */
+  Succeeded: "payment.succeeded"
+};
+var Webhook = {
+  /** The provider event is unsupported or cannot be safely normalized yet. */
+  Unknown: "unknown"
+};
+function createBilling(provider) {
+  return provider;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  Payment,
+  Provider,
+  Subscription,
+  Webhook,
+  createBilling
+});

package/dist/index.d.cts

@@ -0,0 +1,201 @@
+/**
+ * Built-in provider names supported by the portable billing surface.
+ *
+ * Prefer these constants over string literals so refactors stay type-safe.
+ */
+declare const Provider: {
+    /** Stripe provider adapter name. */
+    readonly Stripe: "stripe";
+    /** Dodo Payments provider adapter name. */
+    readonly Dodo: "dodo";
+};
+/**
+ * Union of the provider names declared in {@link Provider}.
+ */
+type BillingProviderName = (typeof Provider)[keyof typeof Provider];
+/**
+ * Portable checkout intent used across providers.
+ *
+ * Some providers model this explicitly, while others infer it from the product
+ * or price being purchased.
+ */
+type BillingMode = "payment" | "subscription";
+/**
+ * Stable normalized subscription event names.
+ */
+declare const Subscription: {
+    /** A subscription became active. */
+    readonly Active: "subscription.active";
+    /** A subscription was cancelled. */
+    readonly Cancelled: "subscription.cancelled";
+};
+/**
+ * Stable normalized payment event names.
+ */
+declare const Payment: {
+    /** A payment completed successfully. */
+    readonly Succeeded: "payment.succeeded";
+};
+/**
+ * Fallback normalized webhook event names.
+ */
+declare const Webhook: {
+    /** The provider event is unsupported or cannot be safely normalized yet. */
+    readonly Unknown: "unknown";
+};
+/**
+ * Shared input shape for starting a hosted checkout flow.
+ */
+interface CreateCheckoutInput {
+    /** Existing provider customer identifier to attach the checkout to. */
+    customerId?: string;
+    /** Customer email used when the provider needs to create or identify a customer. */
+    customerEmail?: string;
+    /** Product identifier used by product-based adapters. Dodo currently requires this field. */
+    productId?: string;
+    /** Price identifier used by price-based adapters. Stripe currently requires this field. */
+    priceId?: string;
+    /** Where the hosted checkout should redirect after a successful purchase. */
+    successUrl: string;
+    /** Where the hosted checkout should redirect if the buyer cancels. */
+    cancelUrl: string;
+    /** Whether the checkout is intended for a one-time payment or a subscription. */
+    mode: BillingMode;
+    /** Optional metadata forwarded to the billing provider when supported. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Shared result returned after creating a hosted checkout session.
+ */
+interface CheckoutResult {
+    /** Provider-specific checkout or session identifier. */
+    id: string;
+    /** Hosted checkout URL to redirect the user to. */
+    url: string;
+    /** Provider that created this checkout session. */
+    provider: BillingProviderName;
+    /** Escape hatch for the raw provider response payload. */
+    raw?: unknown;
+}
+/**
+ * Shared input shape for creating a billing portal or customer-management link.
+ */
+interface CreatePortalLinkInput {
+    /** Provider customer identifier that should gain access to billing management. */
+    customerId: string;
+    /** Where the portal should send the user when they exit the hosted flow. */
+    returnUrl: string;
+}
+/**
+ * Shared result returned after creating a hosted billing portal link.
+ */
+interface PortalLinkResult {
+    /** Hosted billing management URL. */
+    url: string;
+    /** Provider that created this portal link. */
+    provider: BillingProviderName;
+    /** Escape hatch for the raw provider response payload. */
+    raw?: unknown;
+}
+/**
+ * Shared input shape for verifying provider webhook deliveries.
+ */
+interface VerifyWebhookInput {
+    /** Raw request body as received by the application. */
+    payload: string | Uint8Array;
+    /** Optional direct signature value for providers that verify from a single header. */
+    signature?: string;
+    /** Optional secret override when the verification secret is chosen per request. */
+    secret?: string;
+    /** Optional raw headers for providers that require multiple verification headers. */
+    headers?: Record<string, string | undefined>;
+}
+/**
+ * Provider-agnostic webhook events returned by provider adapters.
+ *
+ * Unsupported provider payloads should resolve to {@link Webhook.Unknown}
+ * instead of throwing purely because the event is outside the current MVP.
+ */
+type NormalizedWebhookEvent = {
+    /** Stable subscription activation event name. */
+    type: typeof Subscription.Active;
+    /** Provider that emitted the event. */
+    provider: BillingProviderName;
+    /** Provider customer identifier tied to the subscription. */
+    customerId: string;
+    /** Provider subscription identifier. */
+    subscriptionId: string;
+    /** Escape hatch for the raw provider payload. */
+    raw?: unknown;
+} | {
+    /** Stable subscription cancellation event name. */
+    type: typeof Subscription.Cancelled;
+    /** Provider that emitted the event. */
+    provider: BillingProviderName;
+    /** Provider customer identifier tied to the subscription. */
+    customerId: string;
+    /** Provider subscription identifier. */
+    subscriptionId: string;
+    /** Escape hatch for the raw provider payload. */
+    raw?: unknown;
+} | {
+    /** Stable payment success event name. */
+    type: typeof Payment.Succeeded;
+    /** Provider that emitted the event. */
+    provider: BillingProviderName;
+    /** Provider customer identifier when the provider includes one. */
+    customerId?: string;
+    /** Provider payment identifier. */
+    paymentId: string;
+    /** Escape hatch for the raw provider payload. */
+    raw?: unknown;
+} | {
+    /** Fallback event name for unsupported or partial provider payloads. */
+    type: typeof Webhook.Unknown;
+    /** Provider that emitted the event. */
+    provider: BillingProviderName;
+    /** Raw provider payload preserved for custom handling. */
+    raw?: unknown;
+};
+/**
+ * Minimal contract implemented by every billing provider adapter.
+ */
+interface BillingProvider {
+    /**
+     * Starts a hosted checkout flow for a payment or subscription purchase.
+     */
+    createCheckout(input: CreateCheckoutInput): Promise<CheckoutResult>;
+    /**
+     * Creates a hosted billing-management link for an existing customer.
+     */
+    createPortalLink(input: CreatePortalLinkInput): Promise<PortalLinkResult>;
+    /**
+     * Verifies an incoming webhook request and returns a normalized event.
+     */
+    verifyWebhook(input: VerifyWebhookInput): Promise<NormalizedWebhookEvent>;
+}
+/**
+ * Typed identity helper for provider adapters.
+ *
+ * This keeps provider-specific members on the returned adapter instead of
+ * collapsing everything down to the shared {@link BillingProvider} contract.
+ *
+ * @example
+ * ```ts
+ * const billing = createBilling({
+ *   providerName: Provider.Dodo,
+ *   async createCheckout() {
+ *     // ...
+ *   },
+ *   async createPortalLink() {
+ *     // ...
+ *   },
+ *   async verifyWebhook() {
+ *     // ...
+ *   }
+ * });
+ * ```
+ */
+declare function createBilling<T extends BillingProvider>(provider: T): T;
+
+export { type BillingMode, type BillingProvider, type BillingProviderName, type CheckoutResult, type CreateCheckoutInput, type CreatePortalLinkInput, type NormalizedWebhookEvent, Payment, type PortalLinkResult, Provider, Subscription, type VerifyWebhookInput, Webhook, createBilling };

package/dist/index.d.ts

@@ -0,0 +1,201 @@
+/**
+ * Built-in provider names supported by the portable billing surface.
+ *
+ * Prefer these constants over string literals so refactors stay type-safe.
+ */
+declare const Provider: {
+    /** Stripe provider adapter name. */
+    readonly Stripe: "stripe";
+    /** Dodo Payments provider adapter name. */
+    readonly Dodo: "dodo";
+};
+/**
+ * Union of the provider names declared in {@link Provider}.
+ */
+type BillingProviderName = (typeof Provider)[keyof typeof Provider];
+/**
+ * Portable checkout intent used across providers.
+ *
+ * Some providers model this explicitly, while others infer it from the product
+ * or price being purchased.
+ */
+type BillingMode = "payment" | "subscription";
+/**
+ * Stable normalized subscription event names.
+ */
+declare const Subscription: {
+    /** A subscription became active. */
+    readonly Active: "subscription.active";
+    /** A subscription was cancelled. */
+    readonly Cancelled: "subscription.cancelled";
+};
+/**
+ * Stable normalized payment event names.
+ */
+declare const Payment: {
+    /** A payment completed successfully. */
+    readonly Succeeded: "payment.succeeded";
+};
+/**
+ * Fallback normalized webhook event names.
+ */
+declare const Webhook: {
+    /** The provider event is unsupported or cannot be safely normalized yet. */
+    readonly Unknown: "unknown";
+};
+/**
+ * Shared input shape for starting a hosted checkout flow.
+ */
+interface CreateCheckoutInput {
+    /** Existing provider customer identifier to attach the checkout to. */
+    customerId?: string;
+    /** Customer email used when the provider needs to create or identify a customer. */
+    customerEmail?: string;
+    /** Product identifier used by product-based adapters. Dodo currently requires this field. */
+    productId?: string;
+    /** Price identifier used by price-based adapters. Stripe currently requires this field. */
+    priceId?: string;
+    /** Where the hosted checkout should redirect after a successful purchase. */
+    successUrl: string;
+    /** Where the hosted checkout should redirect if the buyer cancels. */
+    cancelUrl: string;
+    /** Whether the checkout is intended for a one-time payment or a subscription. */
+    mode: BillingMode;
+    /** Optional metadata forwarded to the billing provider when supported. */
+    metadata?: Record<string, string>;
+}
+/**
+ * Shared result returned after creating a hosted checkout session.
+ */
+interface CheckoutResult {
+    /** Provider-specific checkout or session identifier. */
+    id: string;
+    /** Hosted checkout URL to redirect the user to. */
+    url: string;
+    /** Provider that created this checkout session. */
+    provider: BillingProviderName;
+    /** Escape hatch for the raw provider response payload. */
+    raw?: unknown;
+}
+/**
+ * Shared input shape for creating a billing portal or customer-management link.
+ */
+interface CreatePortalLinkInput {
+    /** Provider customer identifier that should gain access to billing management. */
+    customerId: string;
+    /** Where the portal should send the user when they exit the hosted flow. */
+    returnUrl: string;
+}
+/**
+ * Shared result returned after creating a hosted billing portal link.
+ */
+interface PortalLinkResult {
+    /** Hosted billing management URL. */
+    url: string;
+    /** Provider that created this portal link. */
+    provider: BillingProviderName;
+    /** Escape hatch for the raw provider response payload. */
+    raw?: unknown;
+}
+/**
+ * Shared input shape for verifying provider webhook deliveries.
+ */
+interface VerifyWebhookInput {
+    /** Raw request body as received by the application. */
+    payload: string | Uint8Array;
+    /** Optional direct signature value for providers that verify from a single header. */
+    signature?: string;
+    /** Optional secret override when the verification secret is chosen per request. */
+    secret?: string;
+    /** Optional raw headers for providers that require multiple verification headers. */
+    headers?: Record<string, string | undefined>;
+}
+/**
+ * Provider-agnostic webhook events returned by provider adapters.
+ *
+ * Unsupported provider payloads should resolve to {@link Webhook.Unknown}
+ * instead of throwing purely because the event is outside the current MVP.
+ */
+type NormalizedWebhookEvent = {
+    /** Stable subscription activation event name. */
+    type: typeof Subscription.Active;
+    /** Provider that emitted the event. */
+    provider: BillingProviderName;
+    /** Provider customer identifier tied to the subscription. */
+    customerId: string;
+    /** Provider subscription identifier. */
+    subscriptionId: string;
+    /** Escape hatch for the raw provider payload. */
+    raw?: unknown;
+} | {
+    /** Stable subscription cancellation event name. */
+    type: typeof Subscription.Cancelled;
+    /** Provider that emitted the event. */
+    provider: BillingProviderName;
+    /** Provider customer identifier tied to the subscription. */
+    customerId: string;
+    /** Provider subscription identifier. */
+    subscriptionId: string;
+    /** Escape hatch for the raw provider payload. */
+    raw?: unknown;
+} | {
+    /** Stable payment success event name. */
+    type: typeof Payment.Succeeded;
+    /** Provider that emitted the event. */
+    provider: BillingProviderName;
+    /** Provider customer identifier when the provider includes one. */
+    customerId?: string;
+    /** Provider payment identifier. */
+    paymentId: string;
+    /** Escape hatch for the raw provider payload. */
+    raw?: unknown;
+} | {
+    /** Fallback event name for unsupported or partial provider payloads. */
+    type: typeof Webhook.Unknown;
+    /** Provider that emitted the event. */
+    provider: BillingProviderName;
+    /** Raw provider payload preserved for custom handling. */
+    raw?: unknown;
+};
+/**
+ * Minimal contract implemented by every billing provider adapter.
+ */
+interface BillingProvider {
+    /**
+     * Starts a hosted checkout flow for a payment or subscription purchase.
+     */
+    createCheckout(input: CreateCheckoutInput): Promise<CheckoutResult>;
+    /**
+     * Creates a hosted billing-management link for an existing customer.
+     */
+    createPortalLink(input: CreatePortalLinkInput): Promise<PortalLinkResult>;
+    /**
+     * Verifies an incoming webhook request and returns a normalized event.
+     */
+    verifyWebhook(input: VerifyWebhookInput): Promise<NormalizedWebhookEvent>;
+}
+/**
+ * Typed identity helper for provider adapters.
+ *
+ * This keeps provider-specific members on the returned adapter instead of
+ * collapsing everything down to the shared {@link BillingProvider} contract.
+ *
+ * @example
+ * ```ts
+ * const billing = createBilling({
+ *   providerName: Provider.Dodo,
+ *   async createCheckout() {
+ *     // ...
+ *   },
+ *   async createPortalLink() {
+ *     // ...
+ *   },
+ *   async verifyWebhook() {
+ *     // ...
+ *   }
+ * });
+ * ```
+ */
+declare function createBilling<T extends BillingProvider>(provider: T): T;
+
+export { type BillingMode, type BillingProvider, type BillingProviderName, type CheckoutResult, type CreateCheckoutInput, type CreatePortalLinkInput, type NormalizedWebhookEvent, Payment, type PortalLinkResult, Provider, Subscription, type VerifyWebhookInput, Webhook, createBilling };

package/dist/index.js

@@ -0,0 +1,31 @@
+// src/index.ts
+var Provider = {
+  /** Stripe provider adapter name. */
+  Stripe: "stripe",
+  /** Dodo Payments provider adapter name. */
+  Dodo: "dodo"
+};
+var Subscription = {
+  /** A subscription became active. */
+  Active: "subscription.active",
+  /** A subscription was cancelled. */
+  Cancelled: "subscription.cancelled"
+};
+var Payment = {
+  /** A payment completed successfully. */
+  Succeeded: "payment.succeeded"
+};
+var Webhook = {
+  /** The provider event is unsupported or cannot be safely normalized yet. */
+  Unknown: "unknown"
+};
+function createBilling(provider) {
+  return provider;
+}
+export {
+  Payment,
+  Provider,
+  Subscription,
+  Webhook,
+  createBilling
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@openbilling/core",
+  "version": "0.1.0",
+  "homepage": "https://github.com/gndimitro/openbilling",
+  "description": "Switch between Stripe and Dodo Payments without rewriting your billing logic",
+  "license": "MIT",
+  "keywords": [
+    "billing",
+    "payments",
+    "stripe",
+    "dodo"
+  ],
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "dev": "tsup src/index.ts --format esm,cjs --dts --clean --watch",
+    "test": "vitest run",
+    "typecheck": "tsc --project tsconfig.json --noEmit"
+  }
+}