@forklaunch/interfaces-billing 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 forklaunch
+
+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/index.ts

@@ -0,0 +1,5 @@
+export * from './interfaces/billingPortal.service.interface';
+export * from './interfaces/checkoutSession.service.interface';
+export * from './interfaces/paymentLink.service.interface';
+export * from './interfaces/plan.service.interface';
+export * from './interfaces/subscription.service.interface';

package/interfaces/billingPortal.service.interface.ts

@@ -0,0 +1,36 @@
+import { IdDto, RecordTimingDto } from '@forklaunch/common';
+
+export type CreateBillingPortalDto = {
+  customerId: string;
+  uri: string;
+  expiresAt: Date;
+  extraFields?: unknown;
+};
+export type UpdateBillingPortalDto = IdDto & Partial<CreateBillingPortalDto>;
+export type BillingPortalDto = IdDto &
+  CreateBillingPortalDto &
+  Partial<RecordTimingDto>;
+
+export type BillingPortalServiceParameters = {
+  CreateBillingPortalDto: CreateBillingPortalDto;
+  UpdateBillingPortalDto: UpdateBillingPortalDto;
+  BillingPortalDto: BillingPortalDto;
+  IdDto: IdDto;
+};
+
+export interface BillingPortalService<
+  Params extends BillingPortalServiceParameters = BillingPortalServiceParameters
+> {
+  // for generating external links
+  // store in cache, for permissions
+  createBillingPortalSession: (
+    billingPortalDto: Params['CreateBillingPortalDto']
+  ) => Promise<Params['BillingPortalDto']>;
+  getBillingPortalSession: (
+    idDto: Params['IdDto']
+  ) => Promise<Params['BillingPortalDto']>;
+  updateBillingPortalSession: (
+    billingPortalDto: Params['UpdateBillingPortalDto']
+  ) => Promise<Params['BillingPortalDto']>;
+  expireBillingPortalSession: (idDto: Params['IdDto']) => Promise<void>;
+}

package/interfaces/checkoutSession.service.interface.ts

@@ -0,0 +1,40 @@
+import { IdDto, RecordTimingDto } from '@forklaunch/common';
+
+export type CreateCheckoutSessionDto<PaymentMethodEnum> = {
+  customerId: string;
+  paymentMethods: PaymentMethodEnum[keyof PaymentMethodEnum][];
+  metadata?: unknown;
+  successRedirectUri: string;
+  cancelRedirectUri: string;
+  extraFields?: unknown;
+};
+export type UpdateCheckoutSessionDto<PaymentMethodEnum> = IdDto &
+  Partial<CreateCheckoutSessionDto<PaymentMethodEnum>>;
+export type CheckoutSessionDto<PaymentMethodEnum> = IdDto &
+  CreateCheckoutSessionDto<PaymentMethodEnum> &
+  Partial<RecordTimingDto>;
+
+export type CheckoutSessionServiceParameters<PaymentMethodEnum> = {
+  CreateCheckoutSessionDto: CreateCheckoutSessionDto<PaymentMethodEnum>;
+  CheckoutSessionDto: CheckoutSessionDto<PaymentMethodEnum>;
+  IdDto: IdDto;
+};
+
+export interface CheckoutSessionService<
+  PaymentMethodEnum,
+  Params extends
+    CheckoutSessionServiceParameters<PaymentMethodEnum> = CheckoutSessionServiceParameters<PaymentMethodEnum>
+> {
+  // for generating external links
+  // store in cache, for permissions
+  createCheckoutSession: (
+    checkoutSessionDto: Params['CreateCheckoutSessionDto']
+  ) => Promise<Params['CheckoutSessionDto']>;
+  getCheckoutSession: (
+    idDto: Params['IdDto']
+  ) => Promise<Params['CheckoutSessionDto']>;
+  expireCheckoutSession: (idDto: Params['IdDto']) => Promise<void>;
+
+  handleCheckoutSuccess: (idDto: Params['IdDto']) => Promise<void>;
+  handleCheckoutFailure: (idDto: Params['IdDto']) => Promise<void>;
+}

package/interfaces/paymentLink.service.interface.ts

@@ -0,0 +1,49 @@
+import { IdDto, IdsDto, RecordTimingDto } from '@forklaunch/common';
+
+export type CreatePaymentLinkDto<CurrencyEnum> = {
+  amount: number;
+  currency: CurrencyEnum[keyof CurrencyEnum];
+  metadata?: unknown;
+  successRedirectUri: string;
+  cancelRedirectUri: string;
+  extraFields?: unknown;
+};
+export type UpdatePaymentLinkDto<CurrencyEnum> = IdDto &
+  Partial<CreatePaymentLinkDto<CurrencyEnum>>;
+export type PaymentLinkDto<CurrencyEnum> = IdDto &
+  CreatePaymentLinkDto<CurrencyEnum> &
+  Partial<RecordTimingDto>;
+
+export type PaymentLinkServiceParameters<CurrencyEnum> = {
+  CreatePaymentLinkDto: CreatePaymentLinkDto<CurrencyEnum>;
+  UpdatePaymentLinkDto: UpdatePaymentLinkDto<CurrencyEnum>;
+  PaymentLinkDto: PaymentLinkDto<CurrencyEnum>;
+  IdDto: IdDto;
+  IdsDto: IdsDto;
+};
+
+export interface PaymentLinkService<
+  CurrencyEnum,
+  Params extends
+    PaymentLinkServiceParameters<CurrencyEnum> = PaymentLinkServiceParameters<CurrencyEnum>
+> {
+  // for one off products that are not part of a subscription
+  // think about how permissions work on payment links, but these should be ephemeral
+  // store in cache, for permissions
+  createPaymentLink: (
+    paymentLink: Params['CreatePaymentLinkDto']
+  ) => Promise<Params['PaymentLinkDto']>;
+  updatePaymentLink: (
+    paymentLink: Params['UpdatePaymentLinkDto']
+  ) => Promise<Params['PaymentLinkDto']>;
+  getPaymentLink: (idDto: Params['IdDto']) => Promise<Params['PaymentLinkDto']>;
+  expirePaymentLink: (idDto: Params['IdDto']) => Promise<void>;
+
+  handlePaymentSuccess: (idDto: Params['IdDto']) => Promise<void>;
+  handlePaymentFailure: (idDto: Params['IdDto']) => Promise<void>;
+
+  // admin API, make sure that permissions are correct here
+  listPaymentLinks: (
+    idsDto?: Params['IdsDto']
+  ) => Promise<Params['PaymentLinkDto'][]>;
+}

package/interfaces/plan.service.interface.ts

@@ -0,0 +1,54 @@
+import { IdDto, IdsDto, RecordTimingDto } from '@forklaunch/common';
+import { EntityManager } from '@mikro-orm/core';
+
+export type CreatePlanDto<PlanCadenceEnum, BillingProviderEnum> = {
+  active: boolean;
+  name: string;
+  description?: string;
+  price: number;
+  cadence: PlanCadenceEnum[keyof PlanCadenceEnum];
+  features?: string[];
+  extraFields?: unknown;
+  externalId: string;
+  billingProvider?: BillingProviderEnum[keyof BillingProviderEnum];
+};
+export type UpdatePlanDto<PlanCadenceEnum, BillingProviderEnum> = IdDto &
+  Partial<CreatePlanDto<PlanCadenceEnum, BillingProviderEnum>>;
+export type PlanDto<PlanCadenceEnum, BillingProviderEnum> = IdDto &
+  CreatePlanDto<PlanCadenceEnum, BillingProviderEnum> &
+  Partial<RecordTimingDto>;
+
+export type PlanServiceParameters<PlanCadenceEnum, BillingProviderEnum> = {
+  CreatePlanDto: CreatePlanDto<PlanCadenceEnum, BillingProviderEnum>;
+  UpdatePlanDto: UpdatePlanDto<PlanCadenceEnum, BillingProviderEnum>;
+  PlanDto: PlanDto<PlanCadenceEnum, BillingProviderEnum>;
+  IdDto: IdDto;
+  IdsDto: IdsDto;
+};
+
+export interface PlanService<
+  PlanCadenceEnum,
+  BillingProviderEnum,
+  Params extends PlanServiceParameters<
+    PlanCadenceEnum,
+    BillingProviderEnum
+  > = PlanServiceParameters<PlanCadenceEnum, BillingProviderEnum>
+> {
+  createPlan: (
+    planDto: Params['CreatePlanDto'],
+    em?: EntityManager
+  ) => Promise<Params['PlanDto']>;
+  getPlan: (
+    idDto: Params['IdDto'],
+    em?: EntityManager
+  ) => Promise<Params['PlanDto']>;
+  updatePlan: (
+    planDto: Params['UpdatePlanDto'],
+    em?: EntityManager
+  ) => Promise<Params['PlanDto']>;
+  deletePlan: (idDto: Params['IdDto'], em?: EntityManager) => Promise<void>;
+  listPlans: (
+    idsDto?: Params['IdsDto'],
+    em?: EntityManager
+  ) => Promise<Params['PlanDto'][]>;
+}

package/interfaces/subscription.service.interface.ts

@@ -0,0 +1,76 @@
+import { IdDto, IdsDto, RecordTimingDto } from '@forklaunch/common';
+import { EntityManager } from '@mikro-orm/core';
+
+export type CreateSubscriptionDto<PartyType, BillingProviderType> = {
+  partyId: string;
+  partyType: PartyType[keyof PartyType];
+  description?: string;
+  active: boolean;
+  productId: string;
+  extraFields?: unknown;
+  externalId: string;
+  billingProvider?: BillingProviderType[keyof BillingProviderType];
+  startDate: Date;
+  endDate: Date;
+  status: string;
+};
+export type UpdateSubscriptionDto<PartyType, BillingProviderType> = IdDto &
+  Partial<CreateSubscriptionDto<PartyType, BillingProviderType>>;
+export type SubscriptionDto<PartyType, BillingProviderType> = IdDto &
+  CreateSubscriptionDto<PartyType, BillingProviderType> &
+  Partial<RecordTimingDto>;
+
+export type SubscriptionServiceParameters<PartyType, BillingProviderType> = {
+  CreateSubscriptionDto: CreateSubscriptionDto<PartyType, BillingProviderType>;
+  UpdateSubscriptionDto: UpdateSubscriptionDto<PartyType, BillingProviderType>;
+  SubscriptionDto: SubscriptionDto<PartyType, BillingProviderType>;
+  IdDto: IdDto;
+  IdsDto: IdsDto;
+};
+
+export interface SubscriptionService<
+  PartyType,
+  BillingProviderType,
+  Params extends SubscriptionServiceParameters<
+    PartyType,
+    BillingProviderType
+  > = SubscriptionServiceParameters<PartyType, BillingProviderType>
+> {
+  // store this in a table
+  createSubscription: (
+    subscriptionDto: Params['CreateSubscriptionDto'],
+    em?: EntityManager
+  ) => Promise<Params['SubscriptionDto']>;
+  getSubscription: (
+    idDto: Params['IdDto'],
+    em?: EntityManager
+  ) => Promise<Params['SubscriptionDto']>;
+  getUserSubscription: (
+    idDto: Params['IdDto'],
+    em?: EntityManager
+  ) => Promise<Params['SubscriptionDto']>;
+  getOrganizationSubscription: (
+    idDto: Params['IdDto'],
+    em?: EntityManager
+  ) => Promise<Params['SubscriptionDto']>;
+  updateSubscription: (
+    subscriptionDto: Params['UpdateSubscriptionDto'],
+    em?: EntityManager
+  ) => Promise<Params['SubscriptionDto']>;
+  deleteSubscription: (
+    id: Params['IdDto'],
+    em?: EntityManager
+  ) => Promise<void>;
+  listSubscriptions: (
+    idsDto: Params['IdsDto'],
+    em?: EntityManager
+  ) => Promise<Params['SubscriptionDto'][]>;
+  cancelSubscription: (
+    idDto: Params['IdDto'],
+    em?: EntityManager
+  ) => Promise<void>;
+  resumeSubscription: (
+    idDto: Params['IdDto'],
+    em?: EntityManager
+  ) => Promise<void>;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@forklaunch/interfaces-billing",
+  "version": "0.1.0",
+  "description": "Billing interfaces for forklaunch",
+  "homepage": "https://github.com/forklaunch/forklaunch-js#readme",
+  "bugs": {
+    "url": "https://github.com/forklaunch/forklaunch-js/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/forklaunch/forklaunch-js.git"
+  },
+  "license": "MIT",
+  "author": "Forklift Technologies, Inc.",
+  "main": "server.ts",
+  "dependencies": {
+    "@forklaunch/common": "^0.2.5",
+    "@mikro-orm/core": "^6.4.11"
+  },
+  "devDependencies": {
+    "depcheck": "^1.4.7",
+    "prettier": "^3.5.3",
+    "typedoc": "^0.28.1"
+  },
+  "mikro-orm": {
+    "configPaths": [
+      "./mikro-orm.config.ts",
+      "./dist/mikro-orm.config.js"
+    ]
+  },
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist pnpm.lock.yaml node_modules",
+    "docs": "typedoc --out docs *",
+    "format": "prettier --ignore-path=.prettierignore --config .prettierrc '**/*.{ts,tsx,json}' --write",
+    "lint": "eslint . -c eslint.config.mjs",
+    "lint:fix": "eslint . -c eslint.config.mjs --fix",
+    "start": "ENV_FILE_PATH=.env.local NODE_OPTIONS='--import=tsx' node dist/server.js",
+    "start:bun": "bun run migrate:up && bun dist/server.js",
+    "test": "vitest --passWithNoTests"
+  }
+}

package/tsconfig.json

@@ -0,0 +1,7 @@
+{
+  "extends": "../../tsconfig.base.json",
+  "compilerOptions": {
+    "outDir": "dist"
+  },
+  "exclude": ["node_modules", "dist", "eslint.config.mjs"]
+}