@porulle/core 0.10.4 → 0.10.6

package/package.json

@@ -1,38 +1,38 @@
 {
   "name": "@porulle/core",
-  "version": "0.10.4",
+  "version": "0.10.6",
   "license": "MIT",
   "type": "module",
   "exports": {
     ".": {
+      "types": "./src/index.ts",
       "bun": "./src/index.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.js",
-      "types": "./src/index.ts"
+      "require": "./dist/index.js"
     },
     "./schema": {
+      "types": "./src/kernel/database/schema.ts",
       "bun": "./src/kernel/database/schema.ts",
       "import": "./dist/kernel/database/schema.js",
-      "require": "./dist/kernel/database/schema.js",
-      "types": "./src/kernel/database/schema.ts"
+      "require": "./dist/kernel/database/schema.js"
     },
     "./auth-schema": {
+      "types": "./src/auth/auth-schema.ts",
       "bun": "./src/auth/auth-schema.ts",
       "import": "./dist/auth/auth-schema.js",
-      "require": "./dist/auth/auth-schema.js",
-      "types": "./src/auth/auth-schema.ts"
+      "require": "./dist/auth/auth-schema.js"
     },
     "./testing": {
+      "types": "./src/testing.ts",
       "bun": "./src/testing.ts",
       "import": "./dist/testing.js",
-      "require": "./dist/testing.js",
-      "types": "./src/testing.ts"
+      "require": "./dist/testing.js"
     },
     "./drizzle": {
+      "types": "./src/drizzle.ts",
       "bun": "./src/drizzle.ts",
       "import": "./dist/drizzle.js",
-      "require": "./dist/drizzle.js",
-      "types": "./src/drizzle.ts"
+      "require": "./dist/drizzle.js"
     }
   },
   "dependencies": {
@@ -56,8 +56,8 @@
     "eslint": "^9.39.1",
     "typescript": "5.9.2",
     "vitest": "^3.2.4",
-    "@porulle/typescript-config": "0.1.0",
-    "@porulle/eslint-config": "0.1.0"
+    "@porulle/eslint-config": "0.1.0",
+    "@porulle/typescript-config": "0.1.0"
   },
   "publishConfig": {
     "access": "public"

package/src/auth/setup.ts

@@ -122,6 +122,7 @@ export function createAuth(
 
   try {
     const auth = betterAuth({
+      ...(config.auth?.baseURL ? { baseURL: config.auth.baseURL } : {}),
       database: drizzleAdapter(db.db as unknown as Record<string, unknown>, {
         provider: resolveAuthDbProvider(db.provider),
         schema: authSchema,

package/src/config/types.ts

@@ -123,6 +123,14 @@ export interface ApiKeyScopeDefinition {
 }
 
 export interface AuthConfig {
+  /**
+   * Canonical public origin used by Better Auth when constructing callback
+   * URLs and validating requests. Set this explicitly in deployed runtimes
+   * instead of relying on request-header inference.
+   *
+   * @example "https://commerce.example.com"
+   */
+  baseURL?: string;
   /**
    * The default organization ID for single-store deployments.
    * Created by the seed script via `auth.api.createOrganization()`.

package/src/hooks/checkout.ts

@@ -61,7 +61,12 @@ export interface CheckoutData {
   customerId?: string;
   customerGroupIds?: string[];
   currency: string;
+  /** Porulle payment adapter/provider id, e.g. `stripe`. */
   paymentMethodId: string;
+  /** Provider-issued token for the actual payment instrument. */
+  paymentMethodToken?: string;
+  /** Stable retry key shared by order creation and payment authorization. */
+  idempotencyKey?: string;
   lineItems: CheckoutLineItem[];
   subtotal: number;
   discountTotal: number;
@@ -517,6 +522,8 @@ export const authorizePayment: BeforeHook<CheckoutData> = async ({
       amount: number;
       currency: string;
       paymentMethodId: string;
+      paymentMethodToken?: string;
+      idempotencyKey?: string;
       customerId?: string;
       metadata: Record<string, unknown>;
     }): Promise<{
@@ -529,6 +536,12 @@ export const authorizePayment: BeforeHook<CheckoutData> = async ({
     amount: data.total,
     currency: data.currency,
     paymentMethodId: data.paymentMethodId,
+    ...(data.paymentMethodToken !== undefined
+      ? { paymentMethodToken: data.paymentMethodToken }
+      : {}),
+    ...(data.idempotencyKey !== undefined
+      ? { idempotencyKey: data.idempotencyKey }
+      : {}),
     metadata: {
       checkoutId: data.checkoutId,
       cartId: data.cartId,

package/src/interfaces/rest/routes/checkout.ts

@@ -131,6 +131,12 @@ export function checkoutRoutes(kernel: Kernel) {
       cartId: body.cartId,
       currency: body.currency ?? "USD",
       paymentMethodId: body.paymentMethodId,
+      ...(body.paymentMethodToken !== undefined
+        ? { paymentMethodToken: body.paymentMethodToken }
+        : {}),
+      ...(body.idempotencyKey !== undefined
+        ? { idempotencyKey: body.idempotencyKey }
+        : {}),
       lineItems: [],
       subtotal: 0,
       discountTotal: 0,
@@ -194,6 +200,7 @@ export function checkoutRoutes(kernel: Kernel) {
       database: { db: kernel.database.db as PluginDb },
     });
 
+    let pipelineStage = "validate-and-calculate";
     try {
       // Phase 1: DB transaction for validation — releases connection immediately after
       const validated = await kernel.database.transaction(async (_tx) => {
@@ -208,6 +215,7 @@ export function checkoutRoutes(kernel: Kernel) {
 
       // Phase 2: Payment authorization — NO DB connection held while calling Stripe/etc.
       // If Stripe takes 5s, the DB connection pool is not affected.
+      pipelineStage = "authorize-payment";
       context.tx = null;
       const processed = await runBeforeHooks(
         paymentHooks,
@@ -219,6 +227,7 @@ export function checkoutRoutes(kernel: Kernel) {
       // SEC-07: resolve the order's customer server-side. A self-service actor
       // can only attribute the order to its own profile; a client-supplied
       // foreign customerId is ignored unless the actor is staff.
+      pipelineStage = "resolve-customer";
       const customerUuid = await resolveCheckoutCustomerUuid(
         kernel.services.customers,
         actor,
@@ -275,6 +284,7 @@ export function checkoutRoutes(kernel: Kernel) {
       // Checkout is a trusted, already-server-priced pipeline (resolveCurrentPrices
       // + promotions/tax) and reserves stock in its own after-hooks — so it hands
       // the order primitive precomputed totals rather than re-deriving them.
+      pipelineStage = "create-order";
       const order = await kernel.services.orders.create(orderPayload, actor, undefined, {
         trustedPricing: true,
       });
@@ -287,6 +297,7 @@ export function checkoutRoutes(kernel: Kernel) {
       }
 
       if (order.ok && (processed.appliedPromotions?.length ?? 0) > 0) {
+        pipelineStage = "record-promotion-usage";
         await kernel.services.promotions.recordUsage({
           promotions: processed.appliedPromotions ?? [],
           organizationId: order.value.organizationId,
@@ -298,6 +309,7 @@ export function checkoutRoutes(kernel: Kernel) {
       }
 
       if (order.ok) {
+        pipelineStage = "report-tax-transaction";
         await kernel.services.tax.reportTransaction({
           transactionId: order.value.id,
           transactionDate: new Date(),
@@ -330,6 +342,7 @@ export function checkoutRoutes(kernel: Kernel) {
       // Stash paymentMethodId for completeCheckout compensation chain
       context.context.paymentMethodId = processed.paymentMethodId;
 
+      pipelineStage = "complete-checkout";
       const afterReport = await runAfterHooks(
         afterHooks,
         null,
@@ -338,6 +351,7 @@ export function checkoutRoutes(kernel: Kernel) {
         context,
       );
 
+      pipelineStage = "mark-cart-checked-out";
       await kernel.services.cart.markAsCheckedOut(body.cartId, actor);
 
       return c.json(
@@ -356,8 +370,22 @@ export function checkoutRoutes(kernel: Kernel) {
         201,
       );
     } catch (error) {
+      // Validation, payment authorization, or compensated completion may fail
+      // after the cart's atomic active -> checking_out claim. Release only
+      // that transient state so the shopper can correct the problem and retry.
+      await kernel.services.cart.releaseCheckoutClaim(body.cartId).catch(
+        (releaseError: unknown) => {
+          console.error("[checkout] Failed to release cart claim:", {
+            cartId: body.cartId,
+            error: releaseError instanceof Error ? releaseError.message : String(releaseError),
+          });
+        },
+      );
       // Always log the real error — hidden errors in checkout are unacceptable
-      const realMessage = error instanceof Error ? error.message : String(error);
+      const rawMessage = error instanceof Error ? error.message : String(error);
+      const realMessage = rawMessage === "[object ErrorEvent]"
+        ? `Checkout stage "${pipelineStage}" failed: ${rawMessage}`
+        : rawMessage;
       const realStack = error instanceof Error ? error.stack : undefined;
       console.error("[checkout] Pipeline failed:", { message: realMessage, stack: realStack, code: (error as Record<string, unknown>)?.code });
 

package/src/interfaces/rest/schemas/checkout.ts

@@ -5,7 +5,14 @@ import { ErrorSchema, errorResponses } from "./shared.js";
 
 export const CheckoutBodySchema = z.object({
   cartId: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
-  paymentMethodId: z.string().openapi({ example: "pm_card_visa" }),
+  paymentMethodId: z.string().openapi({
+    example: "stripe",
+    description: "Registered Porulle payment adapter/provider id.",
+  }),
+  paymentMethodToken: z.string().min(3).max(255).optional().openapi({
+    example: "pm_card_visa",
+    description: "Provider-issued token for the shopper's payment instrument. This is not the Porulle adapter id.",
+  }),
   idempotencyKey: z.string().min(8).max(255).optional().openapi({
     example: "checkout-8f14e45f-1738312200",
     description: "Client-supplied retry key. A re-submitted checkout with the same key returns the already-created order without re-authorizing payment (safe offline-queue replay).",

package/src/kernel/hooks/executor.ts

@@ -34,6 +34,24 @@ function withTimeout<T>(promiseOrValue: Promise<T> | T, timeoutMs: number, hookN
   });
 }
 
+function actionableHookError(error: unknown, hookName: string): Error {
+  if (error instanceof Error && error.message && error.message !== "[object ErrorEvent]") {
+    return error;
+  }
+  const candidate = error as { error?: unknown; cause?: unknown; message?: unknown } | null;
+  const nested = candidate?.error ?? candidate?.cause;
+  const nestedMessage = nested instanceof Error
+    ? nested.message
+    : nested && typeof nested === "object" && typeof (nested as { message?: unknown }).message === "string"
+      ? String((nested as { message: string }).message)
+      : undefined;
+  const directMessage = typeof candidate?.message === "string" && candidate.message !== "[object ErrorEvent]"
+    ? candidate.message
+    : undefined;
+  const message = nestedMessage || directMessage || String(error);
+  return new Error(`Before-hook "${hookName}" failed: ${message}`, { cause: error });
+}
+
 export async function runBeforeHooks<T>(
   hooks: BeforeHook<T>[],
   data: T,
@@ -54,7 +72,7 @@ export async function runBeforeHooks<T>(
         error: error instanceof Error ? error.message : String(error),
         requestId: context.requestId,
       });
-      throw error; // Re-throw — beforeHooks MUST succeed
+      throw actionableHookError(error, hookName); // Before hooks MUST succeed with actionable context.
     }
   }
   return current;

package/src/modules/cart/repository/index.ts

@@ -148,6 +148,20 @@ export class CartRepository {
     return rows[0];
   }
 
+  /** Release only an in-progress checkout claim; terminal cart states are untouched. */
+  async releaseCheckoutClaim(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<Cart | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(carts)
+      .set({ status: "active", updatedAt: new Date() })
+      .where(and(eq(carts.id, id), eq(carts.status, "checking_out")))
+      .returning();
+    return rows[0];
+  }
+
   async delete(id: string, ctx?: TxContext): Promise<boolean> {
     const db = this.getDb(ctx);
     const result = await db.delete(carts).where(eq(carts.id, id)).returning();

package/src/modules/cart/service.ts

@@ -599,6 +599,17 @@ export class CartService {
     return Ok(claimed);
   }
 
+  /**
+   * Atomically returns a failed checkout claim to `active`. A checked-out,
+   * merged, abandoned, or already-active cart is left untouched.
+   */
+  async releaseCheckoutClaim(
+    cartId: string,
+    ctx?: TxContext,
+  ): Promise<Result<Cart | null>> {
+    return Ok((await this.repo.releaseCheckoutClaim(cartId, ctx)) ?? null);
+  }
+
   /**
    * Creates an anonymous guest cart with a secret token for access control.
    * The secret must be stored client-side (cookie/local storage) and sent

package/src/modules/payments/adapter.ts

@@ -32,6 +32,10 @@ export interface CreatePaymentIntentParams {
   orderId: string;
   customerId?: string;
   metadata?: Record<string, string>;
+  /** Provider token for the shopper-selected payment instrument. */
+  paymentMethodToken?: string;
+  /** Stable key forwarded to the provider so retries cannot create a second intent. */
+  idempotencyKey?: string;
   terminalId?: string;
 }
 

package/src/runtime/server.ts

@@ -39,8 +39,16 @@ type ServerEnv = {
  * Exposed for direct unit testing — see test/server-edge-runtime.test.ts.
  */
 export function isNodeRuntime(): boolean {
+  const workerUserAgent = typeof navigator !== "undefined"
+    ? navigator.userAgent
+    : undefined;
+  const hasWorkersSocketPair = "WebSocketPair" in globalThis;
+  if (workerUserAgent === "Cloudflare-Workers" || hasWorkersSocketPair) {
+    return false;
+  }
   return (
     typeof process !== "undefined" &&
+    typeof process.versions?.node === "string" &&
     typeof process.on === "function" &&
     typeof process.exit === "function"
   );
@@ -150,8 +158,8 @@ export async function createServer(config: CommerceConfig) {
       const ct = c.res.headers.get("content-type");
       if (ct?.includes("json")) {
         try {
-          const body = await c.res.clone().json();
-          if (body?.error?.name === "ZodError") {
+          const body = await c.res.clone().json() as { error?: { name?: string } };
+          if (body.error?.name === "ZodError") {
             c.res = new Response(
               JSON.stringify({ error: { code: "VALIDATION_FAILED", message: "Invalid input." } }),
               { status: 422, headers: { "content-type": "application/json" } },