@mmailaender/convex-creem 0.1.0

package/src/component/schema.ts

@@ -0,0 +1,112 @@
+import { defineSchema, defineTable } from "convex/server";
+import { v } from "convex/values";
+
+const vNullableString = v.union(v.string(), v.null());
+
+export default defineSchema(
+  {
+    customers: defineTable({
+      id: v.string(),
+      entityId: v.string(),
+      email: v.optional(v.string()),
+      name: v.optional(vNullableString),
+      country: v.optional(v.string()),
+      mode: v.optional(v.string()),
+      metadata: v.optional(v.record(v.string(), v.any())),
+      createdAt: v.optional(v.string()),
+      updatedAt: v.optional(v.string()),
+    })
+      .index("entityId", ["entityId"])
+      .index("id", ["id"]),
+    products: defineTable({
+      id: v.string(),
+      name: v.string(),
+      description: v.union(v.string(), v.null()),
+      price: v.number(),
+      currency: v.string(),
+      billingType: v.string(),
+      billingPeriod: v.optional(v.string()),
+      status: v.string(),
+      taxMode: v.optional(v.string()),
+      taxCategory: v.optional(v.string()),
+      imageUrl: v.optional(v.string()),
+      productUrl: v.optional(v.string()),
+      defaultSuccessUrl: v.optional(vNullableString),
+      mode: v.optional(v.string()),
+      features: v.optional(
+        v.array(
+          v.object({
+            id: v.string(),
+            description: v.string(),
+          }),
+        ),
+      ),
+      metadata: v.optional(v.record(v.string(), v.any())),
+      createdAt: v.string(),
+      modifiedAt: v.union(v.string(), v.null()),
+    })
+      .index("id", ["id"])
+      .index("status", ["status"]),
+    subscriptions: defineTable({
+      id: v.string(),
+      customerId: v.string(),
+      productId: v.string(),
+      status: v.string(),
+      amount: v.union(v.number(), v.null()),
+      currency: v.union(v.string(), v.null()),
+      recurringInterval: vNullableString,
+      currentPeriodStart: v.string(),
+      currentPeriodEnd: v.union(v.string(), v.null()),
+      cancelAtPeriodEnd: v.boolean(),
+      startedAt: v.union(v.string(), v.null()),
+      endedAt: v.union(v.string(), v.null()),
+      priceId: v.optional(v.string()),
+      checkoutId: v.union(v.string(), v.null()),
+      metadata: v.record(v.string(), v.any()),
+      collectionMethod: v.optional(v.string()),
+      discountId: v.optional(v.union(v.string(), v.null())),
+      canceledAt: v.optional(v.union(v.string(), v.null())),
+      endsAt: v.optional(v.union(v.string(), v.null())),
+      trialStart: v.optional(v.union(v.string(), v.null())),
+      trialEnd: v.optional(v.union(v.string(), v.null())),
+      seats: v.optional(v.union(v.number(), v.null())),
+      lastTransactionId: v.optional(v.union(v.string(), v.null())),
+      nextTransactionDate: v.optional(v.union(v.string(), v.null())),
+      mode: v.optional(v.string()),
+      createdAt: v.string(),
+      modifiedAt: v.union(v.string(), v.null()),
+    })
+      .index("id", ["id"])
+      .index("customerId", ["customerId"])
+      .index("customerId_status", ["customerId", "status"])
+      .index("customerId_endedAt", ["customerId", "endedAt"]),
+    orders: defineTable({
+      id: v.string(),
+      customerId: v.string(),
+      productId: v.string(),
+      amount: v.number(),
+      currency: v.string(),
+      status: v.string(),
+      type: v.string(),
+      subTotal: v.optional(v.number()),
+      taxAmount: v.optional(v.number()),
+      discountAmount: v.optional(v.number()),
+      amountDue: v.optional(v.number()),
+      amountPaid: v.optional(v.number()),
+      transactionId: v.optional(v.union(v.string(), v.null())),
+      checkoutId: v.optional(v.union(v.string(), v.null())),
+      discountId: v.optional(v.union(v.string(), v.null())),
+      affiliate: v.optional(v.union(v.string(), v.null())),
+      mode: v.optional(v.string()),
+      metadata: v.optional(v.record(v.string(), v.any())),
+      createdAt: v.string(),
+      updatedAt: v.string(),
+    })
+      .index("id", ["id"])
+      .index("customerId", ["customerId"])
+      .index("customerId_productId", ["customerId", "productId"]),
+  },
+  {
+    schemaValidation: true,
+  },
+);

package/src/component/util.test.ts

@@ -0,0 +1,281 @@
+import { describe, expect, it } from "vitest";
+import {
+  convertToDatabaseSubscription,
+  convertToOrder,
+  convertToDatabaseProduct,
+} from "./util.js";
+
+describe("convertToDatabaseSubscription", () => {
+  const baseSubscription = {
+    id: "sub_1",
+    customer: "cus_1",
+    product: "prod_1",
+    status: "active" as const,
+    items: [{ productId: "prod_1", priceId: "price_1", units: 1 }],
+    currentPeriodStartDate: "2026-01-01T00:00:00.000Z",
+    currentPeriodEndDate: "2026-02-01T00:00:00.000Z",
+    createdAt: "2026-01-01T00:00:00.000Z",
+    updatedAt: "2026-01-15T00:00:00.000Z",
+    canceledAt: null,
+    lastTransactionId: "txn_1",
+    nextTransactionDate: "2026-02-01T00:00:00.000Z",
+    mode: "live",
+    discount: null,
+  };
+
+  it("converts an active subscription", () => {
+    const result = convertToDatabaseSubscription(baseSubscription as any);
+    expect(result.id).toBe("sub_1");
+    expect(result.customerId).toBe("cus_1");
+    expect(result.productId).toBe("prod_1");
+    expect(result.status).toBe("active");
+    expect(result.cancelAtPeriodEnd).toBe(false);
+    expect(result.endedAt).toBeNull();
+    expect(result.trialStart).toBeNull();
+    expect(result.trialEnd).toBeNull();
+    expect(result.seats).toBe(1);
+  });
+
+  it("converts a trialing subscription with trial dates", () => {
+    const sub = {
+      ...baseSubscription,
+      status: "trialing" as const,
+    };
+    const result = convertToDatabaseSubscription(sub as any);
+    expect(result.trialStart).toBe("2026-01-01T00:00:00.000Z");
+    expect(result.trialEnd).toBe("2026-02-01T00:00:00.000Z");
+  });
+
+  it("converts a scheduled_cancel subscription with cancelAtPeriodEnd", () => {
+    const sub = {
+      ...baseSubscription,
+      status: "scheduled_cancel" as const,
+      canceledAt: "2026-01-20T00:00:00.000Z",
+    };
+    const result = convertToDatabaseSubscription(sub as any);
+    expect(result.cancelAtPeriodEnd).toBe(true);
+    expect(result.endsAt).toBe("2026-02-01T00:00:00.000Z");
+    expect(result.canceledAt).toBe("2026-01-20T00:00:00.000Z");
+  });
+
+  it("converts a canceled subscription with endedAt", () => {
+    const sub = {
+      ...baseSubscription,
+      status: "canceled" as const,
+      canceledAt: "2026-01-20T00:00:00.000Z",
+    };
+    const result = convertToDatabaseSubscription(sub as any);
+    expect(result.cancelAtPeriodEnd).toBe(false);
+    expect(result.endedAt).toBe("2026-01-20T00:00:00.000Z");
+    expect(result.endsAt).toBeNull();
+  });
+
+  it("throws ConvexError when customer id is missing", () => {
+    const sub = { ...baseSubscription, customer: null };
+    expect(() => convertToDatabaseSubscription(sub as any)).toThrow(
+      "Creem subscription is missing customer id",
+    );
+  });
+
+  it("throws ConvexError when product id is missing", () => {
+    const sub = { ...baseSubscription, product: null, items: [] };
+    expect(() => convertToDatabaseSubscription(sub as any)).toThrow(
+      "Creem subscription is missing product id",
+    );
+  });
+
+  it("extracts product id from items when product entity id is null", () => {
+    const sub = {
+      ...baseSubscription,
+      product: null as any,
+      customer: "cus_1",
+      items: [{ productId: "prod_from_items", priceId: "p1", units: 2 }],
+    };
+    const result = convertToDatabaseSubscription(sub as any);
+    expect(result.productId).toBe("prod_from_items");
+  });
+
+  it("passes rawMetadata option through", () => {
+    const meta = { convexUserId: "user_123" };
+    const result = convertToDatabaseSubscription(baseSubscription as any, {
+      rawMetadata: meta,
+    });
+    expect(result.metadata).toEqual(meta);
+  });
+
+  it("handles customer as object with id", () => {
+    const sub = {
+      ...baseSubscription,
+      customer: { id: "cus_obj" },
+    };
+    const result = convertToDatabaseSubscription(sub as any);
+    expect(result.customerId).toBe("cus_obj");
+  });
+
+  it("handles product as object with id and extracts price/currency", () => {
+    const sub = {
+      ...baseSubscription,
+      product: {
+        id: "prod_obj",
+        price: 1999,
+        currency: "USD",
+        billingPeriod: "every-month",
+      },
+    };
+    const result = convertToDatabaseSubscription(sub as any);
+    expect(result.productId).toBe("prod_obj");
+    expect(result.amount).toBe(1999);
+    expect(result.currency).toBe("USD");
+    expect(result.recurringInterval).toBe("every-month");
+  });
+
+  it("uses discount id when discount is an object", () => {
+    const sub = {
+      ...baseSubscription,
+      discount: { id: "disc_1" },
+    };
+    const result = convertToDatabaseSubscription(sub as any);
+    expect(result.discountId).toBe("disc_1");
+  });
+});
+
+describe("convertToOrder", () => {
+  const baseOrder = {
+    id: "ord_1",
+    customer: "cus_1",
+    product: "prod_1",
+    amount: 2999,
+    currency: "USD",
+    status: "completed",
+    type: "one_time",
+    transaction: "txn_1",
+  };
+
+  it("converts a basic order with camelCase fields", () => {
+    const order = {
+      ...baseOrder,
+      subTotal: 2500,
+      taxAmount: 499,
+      discountAmount: 0,
+      amountDue: 2999,
+      amountPaid: 2999,
+      createdAt: "2026-01-01T00:00:00.000Z",
+      updatedAt: "2026-01-01T00:00:00.000Z",
+    };
+    const result = convertToOrder(order);
+    expect(result.id).toBe("ord_1");
+    expect(result.customerId).toBe("cus_1");
+    expect(result.productId).toBe("prod_1");
+    expect(result.subTotal).toBe(2500);
+    expect(result.taxAmount).toBe(499);
+    expect(result.transactionId).toBe("txn_1");
+  });
+
+  it("falls back to snake_case fields when camelCase is undefined", () => {
+    const order = {
+      ...baseOrder,
+      sub_total: 2500,
+      tax_amount: 499,
+      discount_amount: 0,
+      amount_due: 2999,
+      amount_paid: 2999,
+      created_at: "2026-01-01T00:00:00.000Z",
+      updated_at: "2026-01-01T00:00:00.000Z",
+    };
+    const result = convertToOrder(order);
+    expect(result.subTotal).toBe(2500);
+    expect(result.taxAmount).toBe(499);
+    expect(result.createdAt).toBe("2026-01-01T00:00:00.000Z");
+    expect(result.updatedAt).toBe("2026-01-01T00:00:00.000Z");
+  });
+
+  it("includes checkoutId and metadata from options", () => {
+    const result = convertToOrder(baseOrder, {
+      checkoutId: "chk_1",
+      metadata: { source: "test" },
+    });
+    expect(result.checkoutId).toBe("chk_1");
+    expect(result.metadata).toEqual({ source: "test" });
+  });
+
+  it("defaults customerId to empty string when customer is null", () => {
+    const order = { ...baseOrder, customer: null };
+    const result = convertToOrder(order);
+    expect(result.customerId).toBe("");
+  });
+
+  it("handles optional fields as null/undefined", () => {
+    const result = convertToOrder(baseOrder);
+    expect(result.discountId).toBeNull();
+    expect(result.affiliate).toBeNull();
+    expect(result.checkoutId).toBeNull();
+  });
+});
+
+describe("convertToDatabaseProduct", () => {
+  const baseProduct = {
+    id: "prod_1",
+    name: "Pro Plan",
+    description: "Full access",
+    price: 1999,
+    currency: "USD",
+    billingType: "recurring",
+    billingPeriod: "every-month",
+    status: "active",
+    taxMode: "inclusive",
+    taxCategory: "saas",
+    defaultSuccessUrl: "https://example.com/success",
+    mode: "live",
+    features: [
+      { id: "feat_1", description: "Unlimited access" },
+      { id: "feat_2", description: "Priority support" },
+    ],
+    createdAt: "2026-01-01T00:00:00.000Z",
+    updatedAt: "2026-01-15T00:00:00.000Z",
+  };
+
+  it("converts a full product entity", () => {
+    const result = convertToDatabaseProduct(baseProduct as any);
+    expect(result.id).toBe("prod_1");
+    expect(result.name).toBe("Pro Plan");
+    expect(result.price).toBe(1999);
+    expect(result.currency).toBe("USD");
+    expect(result.billingType).toBe("recurring");
+    expect(result.billingPeriod).toBe("every-month");
+    expect(result.status).toBe("active");
+    expect(result.features).toHaveLength(2);
+    expect(result.features?.[0]?.description).toBe("Unlimited access");
+    expect(result.createdAt).toBe("2026-01-01T00:00:00.000Z");
+    expect(result.modifiedAt).toBe("2026-01-15T00:00:00.000Z");
+  });
+
+  it("handles missing optional fields", () => {
+    const product = {
+      id: "prod_2",
+      name: "Basic",
+      price: 0,
+      currency: "EUR",
+      billingType: "onetime",
+      status: "active",
+      mode: "test",
+      createdAt: "2026-01-01T00:00:00.000Z",
+    };
+    const result = convertToDatabaseProduct(product as any);
+    expect(result.id).toBe("prod_2");
+    expect(result.description).toBeUndefined();
+    expect(result.billingPeriod).toBeUndefined();
+    expect(result.features).toBeUndefined();
+    expect(result.modifiedAt).toBeNull();
+  });
+
+  it("extracts imageUrl and productUrl via cast", () => {
+    const product = {
+      ...baseProduct,
+      imageUrl: "https://img.example.com/pro.png",
+      productUrl: "https://example.com/pro",
+    };
+    const result = convertToDatabaseProduct(product as any);
+    expect(result.imageUrl).toBe("https://img.example.com/pro.png");
+    expect(result.productUrl).toBe("https://example.com/pro");
+  });
+});

package/src/component/util.ts

@@ -0,0 +1,228 @@
+import type {
+  GenericMutationCtx,
+  GenericActionCtx,
+  GenericQueryCtx,
+  GenericDataModel,
+} from "convex/server";
+import type {
+  ProductEntity as CreemProduct,
+  SubscriptionEntity as CreemSubscription,
+} from "creem/models/components";
+import { ConvexError, type Infer } from "convex/values";
+import type schema from "./schema.js";
+
+/** Minimal context type for Convex functions that only need `runQuery`. */
+export type RunQueryCtx = {
+  runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
+};
+/** Minimal context type for Convex functions that need `runQuery` + `runMutation`. */
+export type RunMutationCtx = {
+  runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
+  runMutation: GenericMutationCtx<GenericDataModel>["runMutation"];
+};
+/** Mutation context that also includes `scheduler` for scheduling async follow-up actions. */
+export type RunSchedulerMutationCtx = RunMutationCtx & {
+  scheduler: GenericMutationCtx<GenericDataModel>["scheduler"];
+};
+/** Minimal context type for Convex actions that need `runQuery` + `runMutation` + `runAction`. */
+export type RunActionCtx = {
+  runQuery: GenericQueryCtx<GenericDataModel>["runQuery"];
+  runMutation: GenericMutationCtx<GenericDataModel>["runMutation"];
+  runAction: GenericActionCtx<GenericDataModel>["runAction"];
+};
+
+const toIsoString = (value: unknown): string | null => {
+  if (!value) {
+    return null;
+  }
+  if (value instanceof Date) {
+    return value.toISOString();
+  }
+  if (typeof value === "string") {
+    return value;
+  }
+  return null;
+};
+
+const toIsoStringOrNow = (value: unknown): string => {
+  return toIsoString(value) ?? new Date().toISOString();
+};
+
+const entityId = (value: unknown): string | null => {
+  if (typeof value === "string") {
+    return value;
+  }
+  if (value && typeof value === "object" && "id" in value) {
+    const id = (value as { id?: unknown }).id;
+    if (typeof id === "string") {
+      return id;
+    }
+  }
+  return null;
+};
+
+/** Convert a Creem SDK `SubscriptionEntity` to the Convex DB subscription schema shape. Handles snake_case/camelCase, metadata recovery, and trial/cancel state. */
+export const convertToDatabaseSubscription = (
+  subscription: CreemSubscription,
+  options?: { rawMetadata?: Record<string, unknown> },
+): Infer<typeof schema.tables.subscriptions.validator> => {
+  const customerId = entityId(subscription.customer);
+  if (!customerId) {
+    throw new ConvexError("Creem subscription is missing customer id");
+  }
+  const productId =
+    entityId(subscription.product) ??
+    subscription.items?.[0]?.productId ??
+    null;
+  if (!productId) {
+    throw new ConvexError("Creem subscription is missing product id");
+  }
+  const product =
+    typeof subscription.product === "object" && subscription.product
+      ? subscription.product
+      : null;
+  const now = new Date().toISOString();
+
+  const periodStartStr = toIsoString(subscription.currentPeriodStartDate);
+  const periodEndStr = toIsoString(subscription.currentPeriodEndDate);
+
+  // Only `scheduled_cancel` is the resumable cancel-at-period-end state.
+  // `canceled` means truly ended (even if currentPeriodEnd is in the future).
+  const isScheduledCancel = subscription.status === "scheduled_cancel";
+  const isTrialing = subscription.status === "trialing";
+
+  // SDK's SubscriptionEntity type does not include `metadata` — zod strips it.
+  // Accept rawMetadata from the caller (extracted from the raw webhook object).
+  const metadata =
+    options?.rawMetadata ??
+    (subscription as { metadata?: Record<string, unknown> }).metadata ??
+    {};
+
+  return {
+    id: subscription.id,
+    customerId,
+    productId,
+    status: subscription.status,
+    amount: product?.price ?? null,
+    currency: product?.currency ?? null,
+    recurringInterval: product?.billingPeriod ?? null,
+    currentPeriodStart:
+      periodStartStr ?? toIsoStringOrNow(subscription.createdAt),
+    currentPeriodEnd: periodEndStr,
+    cancelAtPeriodEnd: isScheduledCancel,
+    startedAt: periodStartStr ?? toIsoString(subscription.createdAt),
+    endedAt:
+      subscription.status === "canceled"
+        ? (toIsoString(subscription.canceledAt) ?? now)
+        : null,
+    checkoutId: null,
+    metadata,
+    collectionMethod:
+      (subscription as { collectionMethod?: string }).collectionMethod ??
+      "charge_automatically",
+    discountId:
+      (subscription.discount as { id?: string } | undefined)?.id ?? null,
+    canceledAt: toIsoString(subscription.canceledAt),
+    endsAt: isScheduledCancel ? periodEndStr : null,
+    // Fix: populate trial dates from period dates when status is trialing
+    trialStart: isTrialing ? periodStartStr : null,
+    trialEnd: isTrialing ? periodEndStr : null,
+    seats: subscription.items?.[0]?.units ?? null,
+    lastTransactionId: subscription.lastTransactionId ?? null,
+    nextTransactionDate: toIsoString(subscription.nextTransactionDate),
+    mode: subscription.mode,
+    priceId: subscription.items?.[0]?.priceId,
+    createdAt: toIsoStringOrNow(subscription.createdAt),
+    modifiedAt: toIsoString(subscription.updatedAt),
+  };
+};
+
+/** Convert a raw order object (from checkout webhook) to the Convex DB order schema shape. Handles both snake_case and camelCase field names. */
+export const convertToOrder = (
+  order: {
+    id: string;
+    customer?: string | null;
+    product: string;
+    amount: number;
+    currency: string;
+    status: string;
+    type: string;
+    transaction?: string | null;
+    sub_total?: number;
+    subTotal?: number;
+    tax_amount?: number;
+    taxAmount?: number;
+    discount_amount?: number;
+    discountAmount?: number;
+    amount_due?: number;
+    amountDue?: number;
+    amount_paid?: number;
+    amountPaid?: number;
+    discount?: string | null;
+    affiliate?: string | null;
+    mode?: string;
+    createdAt?: Date | string | null;
+    updatedAt?: Date | string | null;
+    created_at?: string | null;
+    updated_at?: string | null;
+  },
+  options?: {
+    checkoutId?: string | null;
+    metadata?: Record<string, unknown>;
+  },
+): Infer<typeof schema.tables.orders.validator> => {
+  const now = new Date().toISOString();
+  return {
+    id: order.id,
+    customerId: order.customer ?? "",
+    productId: order.product,
+    amount: order.amount,
+    currency: order.currency,
+    status: order.status,
+    type: order.type,
+    subTotal: order.subTotal ?? order.sub_total,
+    taxAmount: order.taxAmount ?? order.tax_amount,
+    discountAmount: order.discountAmount ?? order.discount_amount,
+    amountDue: order.amountDue ?? order.amount_due,
+    amountPaid: order.amountPaid ?? order.amount_paid,
+    transactionId: order.transaction ?? null,
+    checkoutId: options?.checkoutId ?? null,
+    discountId: order.discount ?? null,
+    affiliate: order.affiliate ?? null,
+    mode: order.mode,
+    metadata: (options?.metadata as Record<string, string>) ?? undefined,
+    createdAt:
+      toIsoString(order.createdAt) ?? toIsoString(order.created_at) ?? now,
+    updatedAt:
+      toIsoString(order.updatedAt) ?? toIsoString(order.updated_at) ?? now,
+  };
+};
+
+/** Convert a Creem SDK `ProductEntity` to the Convex DB product schema shape. */
+export const convertToDatabaseProduct = (
+  product: CreemProduct,
+): Infer<typeof schema.tables.products.validator> => {
+  return {
+    id: product.id,
+    name: product.name,
+    description: product.description,
+    price: product.price,
+    currency: product.currency,
+    billingType: product.billingType,
+    billingPeriod: product.billingPeriod,
+    status: product.status,
+    taxMode: product.taxMode,
+    taxCategory: product.taxCategory,
+    imageUrl: (product as { imageUrl?: string }).imageUrl,
+    productUrl: (product as { productUrl?: string }).productUrl,
+    defaultSuccessUrl: product.defaultSuccessUrl,
+    mode: product.mode,
+    features: product.features?.map((f) => ({
+      id: f.id,
+      description: f.description,
+    })),
+    metadata: {},
+    createdAt: toIsoStringOrNow(product.createdAt),
+    modifiedAt: toIsoString(product.updatedAt),
+  };
+};