@01.software/init 0.9.2 → 0.10.0

package/dist/create-app-templates/ecommerce/lib/payment/sync-order-payment.ts

@@ -0,0 +1,96 @@
+import "../server-only-guard.ts";
+import type { CommerceProvider } from "../commerce/provider.ts";
+import { assertAmountEquals } from "./amount-gate.ts";
+import type { PaymentProvider } from "./provider.ts";
+import type { SyncOrderPaymentResult } from "./types.ts";
+
+/**
+ * Reconcile a PG payment into a placed, paid order. In the checkout/placement
+ * model no order exists until this runs: a verified-paid payment promotes the
+ * open Checkout to a paid Order (`orders.confirmPayment`). The order is then
+ * resolved by PG payment id for idempotent retries (return + webhook collapse
+ * to one `paid`).
+ */
+export async function syncOrderPayment(input: {
+  paymentId: string;
+  orderNumber?: string;
+  providerEventId?: string;
+  commerceProvider: CommerceProvider;
+  paymentProvider: PaymentProvider;
+}): Promise<SyncOrderPaymentResult> {
+  const provider = input.paymentProvider.provider;
+
+  // Idempotency: once placed, the order resolves by PG payment id; a repeat
+  // return/webhook for an already-final order is a no-op.
+  const existing = await input.commerceProvider.getOrderByPaymentId({
+    paymentId: input.paymentId,
+    provider,
+  });
+  if (existing?.displayStatus === "paid") {
+    return { status: "paid", orderId: existing.id };
+  }
+  if (existing?.displayStatus === "canceled") {
+    return { status: "canceled", orderId: existing.id };
+  }
+
+  // Verify against the PG by server re-fetch — never a client-supplied amount.
+  const providerPayment = await input.paymentProvider.getPayment(
+    input.paymentId,
+  );
+  if (!providerPayment) {
+    return { status: "payment_not_found", orderId: existing?.id };
+  }
+  if (providerPayment.status === "pending") {
+    return { status: "pending", orderId: existing?.id };
+  }
+  if (providerPayment.status === "failed") {
+    await input.commerceProvider.markPaymentFailed({
+      paymentId: input.paymentId,
+      orderNumber: input.orderNumber,
+      provider,
+      providerEventId: input.providerEventId,
+    });
+    return { status: "failed", orderId: existing?.id };
+  }
+  if (providerPayment.status === "canceled") {
+    await input.commerceProvider.cancelPendingOrder({
+      paymentId: input.paymentId,
+      orderNumber: input.orderNumber,
+      provider,
+      providerEventId: input.providerEventId,
+    });
+    return { status: "canceled", orderId: existing?.id };
+  }
+
+  // paid: place the open checkout into a paid order with the PG-verified
+  // amount. Placement resolves the checkout by `orderNumber` (→ `checkoutToken`).
+  // The return path supplies the orderNumber from the redirect query; a webhook
+  // that arrives first (or instead, e.g. the buyer closed the tab) recovers it
+  // from the PG payment itself — the durable `orderNumber↔pgPaymentId` mapping
+  // threaded into `customData`/`metadata` at request time (#1544 / I6). Only if
+  // neither source has it does the webhook stay pending and defer to the return.
+  const orderNumber = input.orderNumber ?? providerPayment.orderNumber;
+  if (!orderNumber) {
+    return { status: "pending", orderId: existing?.id };
+  }
+
+  // Unconditional amount-equality gate before confirm. The amount we forward is
+  // always the PG re-fetch (`providerPayment.amount`), never a client value;
+  // when a prior placed order is already on record we cross-check the two
+  // independent sources here, and the Console `confirmPayment` endpoint is the
+  // authoritative quote check against the open checkout total in every case.
+  assertAmountEquals({
+    context: `sync:${provider}:${input.paymentId}`,
+    expected: existing?.totalAmount ?? providerPayment.amount,
+    actual: providerPayment.amount,
+  });
+
+  const placed = await input.commerceProvider.confirmOrderPayment({
+    paymentId: input.paymentId,
+    orderNumber,
+    provider,
+    amount: providerPayment.amount,
+    providerEventId: input.providerEventId,
+  });
+  return { status: "paid", orderId: placed.id };
+}

package/dist/create-app-templates/ecommerce/lib/payment/types.ts

@@ -0,0 +1,71 @@
+export type PaymentRequestInput = {
+  paymentId: string;
+  orderNumber: string;
+  orderName: string;
+  amount: number;
+  currency: string;
+  customer: {
+    name: string;
+    email: string;
+    phone: string;
+  };
+};
+
+export type PaymentRequestResult = {
+  ok: boolean;
+  paymentId: string;
+  redirectUrl?: string;
+  clientPayment?: ClientPaymentRequest;
+  reason?: "canceled" | "failed";
+};
+
+export type ClientPaymentRequest =
+  | {
+      provider: "portone";
+      storeId: string;
+      channelKey: string;
+      payMethod: string;
+      paymentId: string;
+      orderNumber: string;
+      orderName: string;
+      amount: number;
+      currency: string;
+      customer: PaymentRequestInput["customer"];
+    }
+  | {
+      provider: "tosspayments";
+      clientKey: string;
+      customerKey?: string;
+      paymentId: string;
+      orderNumber: string;
+      orderName: string;
+      amount: number;
+      currency: string;
+      customer: PaymentRequestInput["customer"];
+    };
+
+export type ProviderPayment = {
+  paymentId: string;
+  status: "pending" | "paid" | "failed" | "canceled";
+  amount: number;
+  provider?: string;
+  /**
+   * Merchant order number recovered from the PG payment itself (PortOne
+   * `customData`, Toss `metadata`), threaded in at `requestPayment` time. This
+   * is the durable `orderNumber↔pgPaymentId` mapping — there is no local index —
+   * and lets a webhook that arrives before (or instead of) the synchronous
+   * return path resolve and place the open checkout (#1544 / I6).
+   */
+  orderNumber?: string;
+};
+
+export type PaymentWebhookEvent = {
+  type: "payment.updated";
+  paymentId: string;
+  eventId: string;
+};
+
+export type SyncOrderPaymentResult = {
+  status: "paid" | "pending" | "failed" | "canceled" | "payment_not_found";
+  orderId?: string;
+};

package/dist/create-app-templates/ecommerce/lib/server-only-guard.ts

@@ -0,0 +1,20 @@
+/**
+ * Runtime server-only guard (#1544 / I6).
+ *
+ * Importing this module from browser-executed code throws immediately — a hard
+ * runtime error, not merely a bundler boundary — so a runtime-bearing module
+ * (PG secret keys, commerce/payment lifecycle, server re-fetch) can never
+ * silently ship to and execute in the client. In Node (the template's
+ * `node --test` domain tests) and in the Next.js server runtime `window` is
+ * `undefined`, so the import is a no-op.
+ *
+ * We deliberately do NOT use the `server-only` npm package: its `default`
+ * export throws under `node --test` (the `react-server` export condition is not
+ * set there), which would break the template's domain tests. A `typeof window`
+ * check gives the same browser protection without that resolution hazard.
+ */
+if (typeof window !== "undefined") {
+  throw new Error(
+    "This module is server-only and must never be imported into client/browser code.",
+  );
+}

package/dist/create-app-templates/ecommerce/next-env.d.ts

@@ -0,0 +1,6 @@
+/// <reference types="next" />
+/// <reference types="next/image-types/global" />
+import "./.next/types/routes.d.ts";
+
+// NOTE: This file should not be edited
+// see https://nextjs.org/docs/app/api-reference/config/typescript for more information.

package/dist/create-app-templates/ecommerce/next.config.ts

@@ -0,0 +1,16 @@
+import type { NextConfig } from "next";
+
+const nextConfig: NextConfig = {
+  devIndicators: false,
+  transpilePackages: ["@01.software/sdk"],
+  images: {
+    remotePatterns: [
+      {
+        protocol: "https",
+        hostname: "images.unsplash.com",
+      },
+    ],
+  },
+};
+
+export default nextConfig;

package/dist/create-app-templates/ecommerce/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "ecommerce",
+  "version": "0.1.1",
+  "private": true,
+  "type": "module",
+  "scripts": {
+    "dev": "next dev",
+    "build": "next build",
+    "start": "next start",
+    "lint": "eslint",
+    "test": "node --test --experimental-strip-types tests/*.test.ts",
+    "check-types": "next typegen && tsc --noEmit"
+  },
+  "dependencies": {
+    "@01.software/sdk": "^0.42.0",
+    "@portone/browser-sdk": "^0.1.8",
+    "@portone/server-sdk": "^0.19.0",
+    "@tosspayments/tosspayments-sdk": "^2.7.0",
+    "next": "16.2.9",
+    "react": "19.2.4",
+    "react-dom": "19.2.4"
+  },
+  "devDependencies": {
+    "@tailwindcss/postcss": "^4.3.0",
+    "@types/node": "^20",
+    "@types/react": "^19",
+    "@types/react-dom": "^19",
+    "eslint": "^9",
+    "eslint-config-next": "16.2.9",
+    "tailwindcss": "^4.3.0",
+    "typescript": "^5"
+  }
+}

package/dist/create-app-templates/ecommerce/postcss.config.mjs

@@ -0,0 +1,7 @@
+const config = {
+  plugins: {
+    "@tailwindcss/postcss": {},
+  },
+};
+
+export default config;

package/dist/create-app-templates/ecommerce/tests/customer-auth.test.ts

@@ -0,0 +1,263 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+
+import {
+  clearSessionToken,
+  readSessionToken,
+  sessionCookieOptions,
+  writeSessionToken,
+  type SessionCookieStore,
+} from "../lib/customer/session.ts";
+import {
+  assertSameOriginJson,
+  CsrfError,
+} from "../lib/customer/route-guard.ts";
+import {
+  loadCustomer,
+  login,
+  register,
+  type CustomerClientFactory,
+} from "../lib/customer/auth-actions.ts";
+import { appConfig } from "../app-config.ts";
+
+// ---- session cookie read/write/clear -------------------------------------
+
+function fakeCookieStore(): SessionCookieStore & {
+  entries: Map<string, string>;
+} {
+  const entries = new Map<string, string>();
+  return {
+    entries,
+    get(name) {
+      const value = entries.get(name);
+      return value === undefined ? undefined : { value };
+    },
+    set(name, value) {
+      entries.set(name, value);
+    },
+    delete(name) {
+      entries.delete(name);
+    },
+  };
+}
+
+test("session: write then read returns the stored token", () => {
+  const store = fakeCookieStore();
+  assert.equal(readSessionToken(store), null);
+  writeSessionToken(store, "jwt-123");
+  assert.equal(store.entries.get(appConfig.customerKey), "jwt-123");
+  assert.equal(readSessionToken(store), "jwt-123");
+});
+
+test("session: clear removes the token", () => {
+  const store = fakeCookieStore();
+  writeSessionToken(store, "jwt-123");
+  clearSessionToken(store);
+  assert.equal(readSessionToken(store), null);
+});
+
+test("session: cookie options are hardened (HttpOnly + SameSite=lax)", () => {
+  const options = sessionCookieOptions();
+  assert.equal(options.httpOnly, true);
+  assert.equal(options.sameSite, "lax");
+  assert.equal(options.path, "/");
+  assert.ok(options.maxAge > 0);
+  // Secure follows NODE_ENV; under test it is not production.
+  assert.equal(options.secure, process.env.NODE_ENV === "production");
+});
+
+// ---- CSRF guard -----------------------------------------------------------
+
+function fakeRequest(headers: Record<string, string>): Request {
+  return { headers: new Headers(headers) } as unknown as Request;
+}
+
+test("csrf: same-origin JSON request passes", () => {
+  assert.doesNotThrow(() =>
+    assertSameOriginJson(
+      fakeRequest({
+        "content-type": "application/json",
+        origin: "https://shop.example",
+        "x-forwarded-host": "shop.example",
+      }),
+    ),
+  );
+});
+
+test("csrf: same-origin without Origin header passes (non-browser)", () => {
+  assert.doesNotThrow(() =>
+    assertSameOriginJson(
+      fakeRequest({ "content-type": "application/json; charset=utf-8" }),
+    ),
+  );
+});
+
+test("csrf: non-JSON content-type is rejected hard", () => {
+  assert.throws(
+    () =>
+      assertSameOriginJson(
+        fakeRequest({
+          "content-type": "application/x-www-form-urlencoded",
+          origin: "https://shop.example",
+          "x-forwarded-host": "shop.example",
+        }),
+      ),
+    CsrfError,
+  );
+});
+
+test("csrf: cross-origin request is rejected", () => {
+  assert.throws(
+    () =>
+      assertSameOriginJson(
+        fakeRequest({
+          "content-type": "application/json",
+          origin: "https://evil.example",
+          "x-forwarded-host": "shop.example",
+        }),
+      ),
+    CsrfError,
+  );
+});
+
+// ---- auth actions (SDK mocked) -------------------------------------------
+
+function fakeFactory(
+  client: unknown | null,
+): CustomerClientFactory {
+  return async () => client as never;
+}
+
+const SAMPLE_CUSTOMER = { id: "cust_1", name: "Ada", email: "ada@example.com" };
+
+test("login: returns token + customer on success", async () => {
+  const factory = fakeFactory({
+    customer: {
+      auth: {
+        async login() {
+          return { token: "jwt-xyz", customer: SAMPLE_CUSTOMER };
+        },
+      },
+    },
+  });
+  const result = await login(
+    { email: "ada@example.com", password: "pw" },
+    factory,
+  );
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.token, "jwt-xyz");
+    assert.deepEqual(result.customer, SAMPLE_CUSTOMER);
+  }
+});
+
+test("login: maps SDK error status to a failure result", async () => {
+  const factory = fakeFactory({
+    customer: {
+      auth: {
+        async login() {
+          throw Object.assign(new Error("Invalid credentials"), {
+            status: 401,
+          });
+        },
+      },
+    },
+  });
+  const result = await login(
+    { email: "ada@example.com", password: "wrong" },
+    factory,
+  );
+  assert.equal(result.ok, false);
+  if (!result.ok) {
+    assert.equal(result.status, 401);
+    assert.equal(result.message, "Invalid credentials");
+  }
+});
+
+test("login: returns 503 when customer auth is unconfigured", async () => {
+  const result = await login(
+    { email: "ada@example.com", password: "pw" },
+    fakeFactory(null),
+  );
+  assert.equal(result.ok, false);
+  if (!result.ok) assert.equal(result.status, 503);
+});
+
+test("register: returns customer with no token", async () => {
+  const factory = fakeFactory({
+    customer: {
+      auth: {
+        async register() {
+          return { customer: SAMPLE_CUSTOMER };
+        },
+      },
+    },
+  });
+  const result = await register(
+    { name: "Ada", email: "ada@example.com", password: "pw" },
+    factory,
+  );
+  assert.equal(result.ok, true);
+  if (result.ok) {
+    assert.equal(result.token, null);
+    assert.deepEqual(result.customer, SAMPLE_CUSTOMER);
+  }
+});
+
+// ---- 401 -> clear-cookie fallback ----------------------------------------
+
+test("loadCustomer: no token resolves to guest without calling the SDK", async () => {
+  let called = false;
+  const factory: CustomerClientFactory = async () => {
+    called = true;
+    return null;
+  };
+  const result = await loadCustomer(null, factory);
+  assert.equal(result, null);
+  assert.equal(called, false);
+});
+
+test("loadCustomer: valid token resolves the customer", async () => {
+  const factory = fakeFactory({
+    customer: {
+      auth: {
+        async me() {
+          return SAMPLE_CUSTOMER;
+        },
+      },
+    },
+  });
+  const result = await loadCustomer("jwt-ok", factory);
+  assert.deepEqual(result, SAMPLE_CUSTOMER);
+});
+
+test("loadCustomer: expired token (me() -> null on 401) falls back to guest", async () => {
+  const factory = fakeFactory({
+    customer: {
+      auth: {
+        // SDK me() returns null on 401 instead of throwing.
+        async me() {
+          return null;
+        },
+      },
+    },
+  });
+  const result = await loadCustomer("jwt-expired", factory);
+  assert.equal(result, null);
+});
+
+test("loadCustomer: backend error falls back to guest (never throws in render)", async () => {
+  const factory = fakeFactory({
+    customer: {
+      auth: {
+        async me() {
+          throw Object.assign(new Error("Service unavailable"), {
+            status: 503,
+          });
+        },
+      },
+    },
+  });
+  const result = await loadCustomer("jwt-ok", factory);
+  assert.equal(result, null);
+});