Merge pull request #236 from udecode/codex/stable-query-options-args

Author: zbeyens

.changeset/stripe-subscription-timestamps.md

@@ -0,0 +1,7 @@
+---
+"kitcn": patch
+---
+
+## Patches
+
+- Fix auth Stripe subscription writes so `createdAt` and `updatedAt` are only written when the target table defines them.

bun.lock

@@ -0,0 +1,95 @@
+---
+title: Auth plugin timestamp writes must respect table schema
+date: 2026-04-22
+category: integration-issues
+module: auth-adapter
+problem_type: integration_issue
+component: authentication
+symptoms:
+  - Better Auth Stripe subscription upgrade fails with Convex schema validation
+  - Convex reports extra `createdAt` or `updatedAt` on the `subscription` table
+  - `@better-auth/stripe` writes `updatedAt` even though its subscription schema omits it
+root_cause: wrong_api
+resolution_type: code_fix
+severity: high
+tags: [auth, better-auth, stripe, subscriptions, timestamps, schema]
+---
+
+# Auth plugin timestamp writes must respect table schema
+
+## Problem
+
+Stripe subscription flows can write timestamp fields that the Stripe plugin's
+own Better Auth schema does not define. Convex rejects those writes when the
+generated `subscription` table omits `createdAt` and `updatedAt`.
+
+## Symptoms
+
+- `/api/auth/subscription/upgrade` fails during Better Auth Stripe upgrade.
+- Convex throws an extra-field validator error for `createdAt` or `updatedAt`.
+- The failure happens before subscription state can be patched.
+
+## What Didn't Work
+
+- Treating `createdAt` and `updatedAt` as universal auth fields. Core Better
+  Auth tables use them, but plugin tables do not always opt in.
+- Looking only at core Better Auth tables. `@better-auth/stripe` lives in a
+  separate package and its `subscription` schema has no timestamp fields.
+
+## Solution
+
+Resolve the concrete write field set for the target model before auth writes.
+Use the Convex table validator when available, then fall back to the Better Auth
+schema. Only synthesize or preserve auth timestamp fields when that target table
+defines them.
+
+```ts
+const stripUnsupportedAuthTimestamps = (
+  data: Record<string, unknown>,
+  schema: Schema,
+  betterAuthSchema: any,
+  model: string
+) => {
+  const writeFields = resolveWriteFields(schema, betterAuthSchema, model);
+  if (!writeFields) {
+    return data;
+  }
+
+  let result: Record<string, unknown> | undefined;
+  for (const field of ["createdAt", "updatedAt"] as const) {
+    if (field in data && !writeFields.has(field)) {
+      result ??= { ...data };
+      delete result[field];
+    }
+  }
+
+  return result ?? data;
+};
+```
+
+Cover both paths:
+
+- creates should not inject timestamps into plugin tables without those fields
+- updates should strip unsupported `updatedAt` before `ctx.db.patch()` or ORM
+  `set()`
+
+## Why This Works
+
+The generated auth runtime is the last boundary before Convex validates the
+document. Filtering there fixes db and ORM writes without hiding arbitrary schema
+mistakes: only the known auth timestamp fields get special treatment.
+
+## Prevention
+
+- When adding auth plugin support, inspect the plugin package's schema, not only
+  Better Auth core tables.
+- Add regression tests for plugin tables that intentionally omit core auth
+  fields.
+- Do not assume `createdAt` and `updatedAt` are universal across auth plugin
+  tables.
+
+## Related Issues
+
+- [Better Auth 1.6 support needs structural Convex auth wrappers](./better-auth-1-6-support-needs-structural-convex-auth-wrappers-20260416.md)
+- [Convex Better Auth upstream sync must filter runtime fixes from repo churn](./convex-better-auth-upstream-sync-runtime-fixes-20260416.md)
+- [Root auth schema sync should merge missing fragments into local tables](./root-auth-schema-sync-should-merge-missing-fragments-into-local-tables-20260328.md)

docs/solutions/integration-issues/auth-plugin-timestamp-writes-must-respect-table-schema-20260422.md

@@ -14,4 +14,4 @@ RESEND_API_KEY=
 POLAR_SERVER=sandbox
 POLAR_ACCESS_TOKEN=
 POLAR_WEBHOOK_SECRET=
-POLAR_PRODUCT_PREMIUM=
+POLAR_PRODUCT_PREMIUM=

example/convex/.env.example

@@ -923,6 +923,53 @@ export type DataModel = {
     searchIndexes: {};
     vectorIndexes: {};
   };
+  subscription: {
+    document: {
+      billingInterval?: null | string;
+      cancelAt?: null | number;
+      cancelAtPeriodEnd?: null | boolean;
+      canceledAt?: null | number;
+      endedAt?: null | number;
+      periodEnd?: null | number;
+      periodStart?: null | number;
+      plan: string;
+      referenceId: string;
+      seats?: null | number;
+      status?: null | string;
+      stripeCustomerId?: null | string;
+      stripeScheduleId?: null | string;
+      stripeSubscriptionId?: null | string;
+      trialEnd?: null | number;
+      trialStart?: null | number;
+      _id: Id<"subscription">;
+      _creationTime: number;
+    };
+    fieldPaths:
+      | "_creationTime"
+      | "_id"
+      | "billingInterval"
+      | "cancelAt"
+      | "cancelAtPeriodEnd"
+      | "canceledAt"
+      | "endedAt"
+      | "periodEnd"
+      | "periodStart"
+      | "plan"
+      | "referenceId"
+      | "seats"
+      | "status"
+      | "stripeCustomerId"
+      | "stripeScheduleId"
+      | "stripeSubscriptionId"
+      | "trialEnd"
+      | "trialStart";
+    indexes: {
+      by_id: ["_id"];
+      by_creation_time: ["_creationTime"];
+    };
+    searchIndexes: {};
+    vectorIndexes: {};
+  };
   subscriptions: {
     document: {
       amount?: null | number;
@@ -1250,6 +1297,7 @@ export type DataModel = {
       name: string;
       personalOrganizationId?: null | string;
       role?: null | string;
+      stripeCustomerId?: null | string;
       updatedAt: number;
       userId?: null | string;
       username?: null | string;
@@ -1282,6 +1330,7 @@ export type DataModel = {
       | "name"
       | "personalOrganizationId"
       | "role"
+      | "stripeCustomerId"
       | "updatedAt"
       | "userId"
       | "username"

example/convex/functions/_generated/dataModel.d.ts

@@ -1,6 +1,8 @@
+import { stripe } from '@better-auth/stripe';
 import { admin, anonymous, organization, username } from 'better-auth/plugins';
 import { convex } from 'kitcn/auth';
 import { requireSchedulerCtx } from 'kitcn/server';
+import Stripe from 'stripe';
 import { getEnv } from '../lib/get-env';
 import {
   AUTH_DEMO_ANON_EMAIL_DOMAIN,
@@ -11,6 +13,10 @@ import { internal } from './_generated/api';
 import authConfig from './auth.config';
 import { defineAuth } from './generated/auth';
 
+const STRIPE_EXAMPLE_PRICE_ID = 'price_kitcn_example';
+const STRIPE_EXAMPLE_SECRET_KEY = 'sk_test_kitcn_example';
+const STRIPE_EXAMPLE_WEBHOOK_SECRET = 'whsec_kitcn_example';
+
 export default defineAuth((ctx) => {
   const env = getEnv();
 
@@ -90,6 +96,19 @@ export default defineAuth((ctx) => {
           );
         },
       }),
+      stripe({
+        stripeClient: new Stripe(STRIPE_EXAMPLE_SECRET_KEY),
+        stripeWebhookSecret: STRIPE_EXAMPLE_WEBHOOK_SECRET,
+        subscription: {
+          enabled: true,
+          plans: [
+            {
+              name: 'premium',
+              priceId: STRIPE_EXAMPLE_PRICE_ID,
+            },
+          ],
+        },
+      }),
       convex({
         authConfig,
         jwks: env.JWKS,

example/convex/functions/auth.ts

@@ -29,6 +29,10 @@
           "session": {
             "owner": "local"
           },
+          "subscription": {
+            "checksum": "bc65c00ae14d",
+            "owner": "managed"
+          },
           "user": {
             "owner": "local"
           },

example/convex/functions/plugins.lock.json

@@ -213,6 +213,7 @@ export const userTable = convexTable(
     }),
     displayUsername: text(),
     userId: text(),
+    stripeCustomerId: text(),
   },
   (t) => [
     uniqueIndex('email').on(t.email),
@@ -603,6 +604,25 @@ export const triggerDemoRunTable = convexTable(
   (t) => [index('ownerId').on(t.ownerId)]
 );
 
+export const subscriptionTable = convexTable('subscription', {
+  plan: text().notNull(),
+  referenceId: text().notNull(),
+  stripeCustomerId: text(),
+  stripeSubscriptionId: text(),
+  status: text(),
+  periodStart: timestamp(),
+  periodEnd: timestamp(),
+  trialStart: timestamp(),
+  trialEnd: timestamp(),
+  cancelAtPeriodEnd: boolean(),
+  cancelAt: timestamp(),
+  canceledAt: timestamp(),
+  endedAt: timestamp(),
+  seats: integer(),
+  billingInterval: text(),
+  stripeScheduleId: text(),
+});
+
 export const tables = {
   session: sessionTable,
   account: accountTable,
@@ -626,6 +646,7 @@ export const tables = {
   triggerDemoAudit: triggerDemoAuditTable,
   triggerDemoStats: triggerDemoStatsTable,
   triggerDemoRun: triggerDemoRunTable,
+  subscription: subscriptionTable,
 };
 
 const schema = defineSchema(tables, {

example/convex/functions/schema.ts

@@ -31,14 +31,16 @@
     "typecheck:watch": "tsc --noEmit --watch"
   },
   "dependencies": {
-    "@kitcn/resend": "workspace:*",
+    "@better-auth/stripe": "1.6.5",
     "@convex-dev/react-query": "0.1.0",
     "@hookform/resolvers": "5.2.2",
+    "@kitcn/resend": "workspace:*",
+    "@opentelemetry/api": "1.9.0",
     "@react-email/components": "1.0.8",
     "@react-email/render": "2.0.4",
     "@t3-oss/env-nextjs": "0.13.10",
+    "@tanstack/react-query": "5.95.2",
     "better-auth": "1.6.5",
-    "kitcn": "workspace:*",
     "class-variance-authority": "0.7.1",
     "clsx": "2.1.1",
     "cmdk": "1.1.1",
@@ -49,6 +51,7 @@
     "hono": "4.12.9",
     "input-otp": "1.4.2",
     "jotai-x": "2.3.3",
+    "kitcn": "workspace:*",
     "lucide-react": "0.575.0",
     "next-themes": "0.4.6",
     "nuqs": "2.8.8",
@@ -61,14 +64,14 @@
     "react-resizable-panels": "3.0.6",
     "recharts": "2.15.4",
     "sonner": "2.0.7",
+    "stripe": "^22.0.1",
     "superjson": "2.2.6",
     "tailwind-merge": "3.5.0",
     "ts-essentials": "10.1.1",
     "tsx": "4.21.0",
     "type-fest": "5.4.4",
     "use-debounce": "10.1.0",
-    "vaul": "1.1.2",
-    "@tanstack/react-query": "5.95.2"
+    "vaul": "1.1.2"
   },
   "devDependencies": {
     "@tailwindcss/postcss": "4.2.1",

example/package.json

@@ -1,3 +1,4 @@
+import { stripeClient } from '@better-auth/stripe/client';
 import { type Auth, ac, roles } from '@convex/auth-shared';
 import {
   adminClient,
@@ -24,6 +25,7 @@ export const authClient = createAuthClient({
       ac,
       roles,
     }),
+    stripeClient({ subscription: true }),
     convexClient(),
   ],
 });