@porulle/core 0.1.0

package/src/modules/shipping/service.ts

@@ -0,0 +1,51 @@
+import type { CommerceConfig } from "../../config/types.js";
+import { Ok, type Result } from "../../kernel/result.js";
+import type { TxContext } from "../../kernel/database/tx-context.js";
+import type { CatalogRepository } from "../catalog/repository/index.js";
+import {
+  calculateShippingCost,
+  type ShippingAddress,
+  type ShippingLineItem,
+} from "./calculator.js";
+
+interface ShippingServiceDeps {
+  config: CommerceConfig;
+  catalogRepository: CatalogRepository;
+}
+
+export interface CalculateShippingInput {
+  lineItems: ShippingLineItem[];
+  subtotalAfterDiscount: number;
+  currency: string;
+  address?: ShippingAddress;
+  isFreeShipping?: boolean;
+}
+
+export class ShippingService {
+  private readonly catalogRepo: CatalogRepository;
+
+  constructor(private deps: ShippingServiceDeps) {
+    this.catalogRepo = deps.catalogRepository;
+  }
+
+  async calculate(
+    input: CalculateShippingInput,
+    ctx?: TxContext,
+  ): Promise<
+    Result<{ amount: number; strategy: string; weightGrams: number }>
+  > {
+    const result = await calculateShippingCost(
+      this.deps.config,
+      this.catalogRepo,
+      {
+        lineItems: input.lineItems,
+        subtotalAfterDiscount: input.subtotalAfterDiscount,
+        currency: input.currency,
+        isFreeShipping: input.isFreeShipping ?? false,
+        ...(input.address !== undefined ? { address: input.address } : {}),
+      },
+      ctx,
+    );
+    return Ok(result);
+  }
+}

package/src/modules/tax/adapter.ts

@@ -0,0 +1,60 @@
+import type { Result } from "../../kernel/result.js";
+
+export interface TaxAddress {
+  country: string;
+  postalCode: string;
+  state?: string;
+  city?: string;
+  line1?: string;
+}
+
+export interface TaxLineItem {
+  id: string;
+  entityId: string;
+  description: string;
+  quantity: number;
+  unitPrice: number;
+  discount?: number;
+  productTaxCode?: string;
+}
+
+export interface TaxCalculationParams {
+  currency: string;
+  customerId?: string;
+  orderId?: string;
+  fromAddress?: TaxAddress;
+  toAddress?: TaxAddress;
+  shippingAmount: number;
+  lineItems: TaxLineItem[];
+}
+
+export interface TaxCalculationResult {
+  amountToCollect: number;
+  taxableAmount: number;
+  rate: number;
+  breakdown?: Record<string, unknown>;
+}
+
+export interface TaxReportParams {
+  transactionId: string;
+  transactionDate: Date;
+  currency: string;
+  customerId?: string;
+  fromAddress?: TaxAddress;
+  toAddress?: TaxAddress;
+  amount: number;
+  shipping: number;
+  salesTax: number;
+  lineItems: TaxLineItem[];
+}
+
+export interface TaxVoidParams {
+  transactionId: string;
+}
+
+export interface TaxAdapter {
+  readonly providerId: string;
+  calculateTax(params: TaxCalculationParams): Promise<Result<TaxCalculationResult>>;
+  reportTransaction(params: TaxReportParams): Promise<Result<{ transactionId: string }>>;
+  voidTransaction(params: TaxVoidParams): Promise<Result<{ transactionId: string }>>;
+}

package/src/modules/tax/module.ts

@@ -0,0 +1,16 @@
+import type { CommerceConfig } from "../../config/types.js";
+import { defineModule } from "../../kernel/module/index.js";
+import { TaxService } from "./service.js";
+
+export const taxModule = defineModule<
+  Record<string, never>,
+  TaxService,
+  Record<string, never>
+>({
+  id: "tax",
+  schema: () => ({}),
+  service: (deps) =>
+    new TaxService({
+      adapter: (deps.config as CommerceConfig).tax?.adapter,
+    }),
+});

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

@@ -0,0 +1,6 @@
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+
+export interface TaxRepository {
+  // RFC-002 scaffold: module repositories become the only persistence boundary.
+  ping(ctx: TxContext): Promise<void>;
+}

package/src/modules/tax/service.ts

@@ -0,0 +1,53 @@
+import { CommerceValidationError } from "../../kernel/errors.js";
+import { Err, Ok, type Result } from "../../kernel/result.js";
+import type {
+  TaxAdapter,
+  TaxCalculationParams,
+  TaxCalculationResult,
+  TaxReportParams,
+  TaxVoidParams,
+} from "./adapter.js";
+
+interface TaxServiceDeps {
+  adapter: TaxAdapter | undefined;
+}
+
+export class TaxService {
+  private adapter: TaxAdapter | undefined;
+
+  constructor(deps: TaxServiceDeps) {
+    this.adapter = deps.adapter;
+  }
+
+  async calculate(params: TaxCalculationParams): Promise<Result<TaxCalculationResult>> {
+    if (!this.adapter) {
+      return Ok({
+        amountToCollect: 0,
+        taxableAmount:
+          params.lineItems.reduce(
+            (sum, lineItem) => sum + lineItem.unitPrice * lineItem.quantity - (lineItem.discount ?? 0),
+            0,
+          ) + params.shippingAmount,
+        rate: 0,
+      });
+    }
+    return this.adapter.calculateTax(params);
+  }
+
+  async reportTransaction(params: TaxReportParams): Promise<Result<{ transactionId: string }>> {
+    if (!this.adapter) return Ok({ transactionId: params.transactionId });
+    return this.adapter.reportTransaction(params);
+  }
+
+  async voidTransaction(params: TaxVoidParams): Promise<Result<{ transactionId: string }>> {
+    if (!this.adapter) return Ok({ transactionId: params.transactionId });
+    return this.adapter.voidTransaction(params);
+  }
+
+  requireConfigured(): Result<TaxAdapter> {
+    if (!this.adapter) {
+      return Err(new CommerceValidationError("Tax adapter is not configured."));
+    }
+    return Ok(this.adapter);
+  }
+}

package/src/modules/webhooks/hook.ts

@@ -0,0 +1,41 @@
+import { resolveOrgId } from "../../auth/org.js";
+import type { AfterHook } from "../../kernel/hooks/types.js";
+
+/**
+ * Webhook delivery hook — enqueues delivery jobs instead of blocking.
+ *
+ * Previously, this hook made synchronous HTTP calls to each webhook endpoint
+ * inside the request handler, blocking the response for seconds if endpoints
+ * were slow or down.
+ *
+ * Now it enqueues a background job per endpoint. The job runner delivers
+ * asynchronously with retries. The HTTP response returns immediately.
+ */
+export const deliverWebhooks: AfterHook<unknown> = async ({ result, operation, context }) => {
+  const eventName = `${String(context.context.moduleName ?? "unknown")}.${operation}`;
+  const webhooksService = context.services.webhooks as {
+    getEndpointsForEvent(event: string, orgId: string): Promise<{ ok: boolean; value: Array<{ id: string; url: string; secret: string }> }>;
+  };
+
+  // VAPT r2 (codex) finding: fan-out queried ALL endpoints across the
+  // database, so Tenant B's webhooks fired on Tenant A's events —
+  // payload-level cross-tenant data leak. Now scoped to the actor's org.
+  const orgId = resolveOrgId(context.actor);
+
+  const endpoints = await webhooksService.getEndpointsForEvent(eventName, orgId);
+  if (!endpoints.ok) return;
+
+  for (const endpoint of endpoints.value) {
+    await context.jobs.enqueue("webhooks/deliver", {
+      endpointId: endpoint.id,
+      endpointUrl: endpoint.url,
+      endpointSecret: endpoint.secret,
+      eventName,
+      payload: result,
+    }, {
+      organizationId: orgId,
+      maxAttempts: 5,
+      queue: "webhooks",
+    });
+  }
+};

package/src/modules/webhooks/index.ts

@@ -0,0 +1 @@
+export { webhooksModule } from "./module.js";

package/src/modules/webhooks/module.ts

@@ -0,0 +1,22 @@
+import { defineModule } from "../../kernel/module/index.js";
+import type { DrizzleDatabase } from "../../kernel/database/drizzle-db.js";
+import { WebhooksRepository } from "./repository/index.js";
+import { WebhookService } from "./service.js";
+import {
+  processedWebhookEvents,
+  webhookDeliveries,
+  webhookEndpoints,
+} from "./schema.js";
+
+export const webhooksModule = defineModule({
+  id: "webhooks",
+  schema: () => ({
+    webhookEndpoints,
+    processedWebhookEvents,
+    webhookDeliveries,
+  }),
+  service: (deps) =>
+    new WebhookService({
+      repository: new WebhooksRepository(deps.db.db as DrizzleDatabase),
+    }),
+});

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

@@ -0,0 +1,304 @@
+import { eq, and, lte, isNull, or, desc, sql } from "drizzle-orm";
+import type { TxContext } from "../../../kernel/database/tx-context.js";
+import type {
+  DrizzleDatabase,
+  DbOrTx,
+} from "../../../kernel/database/drizzle-db.js";
+import { webhookEndpoints, webhookDeliveries } from "../schema.js";
+
+// Infer types from Drizzle schema
+export type WebhookEndpoint = typeof webhookEndpoints.$inferSelect;
+export type WebhookEndpointInsert = typeof webhookEndpoints.$inferInsert;
+export type WebhookDelivery = typeof webhookDeliveries.$inferSelect;
+export type WebhookDeliveryInsert = typeof webhookDeliveries.$inferInsert;
+
+/**
+ * WebhooksRepository provides type-safe database operations for webhooks.
+ *
+ * This repository manages webhook endpoints and their delivery tracking.
+ * All methods support an optional TxContext parameter for transaction participation.
+ */
+export class WebhooksRepository {
+  constructor(private readonly db: DrizzleDatabase) {}
+
+  private getDb(ctx?: TxContext): DbOrTx {
+    return (ctx?.tx as DbOrTx | undefined) ?? this.db;
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Webhook Endpoints
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  // VAPT r2 (codex) finding: every read/delete on webhookEndpoints was
+  // org-agnostic. A tenant could list/delete other tenants' endpoints
+  // (HIGH cross-tenant), and event fan-out queried all endpoints in the
+  // database — Tenant B's webhooks fired on Tenant A's events, leaking
+  // payload across tenants. Org filtering is now mandatory.
+  async findEndpointById(
+    id: string,
+    orgId: string,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(webhookEndpoints)
+      .where(
+        and(
+          eq(webhookEndpoints.id, id),
+          eq(webhookEndpoints.organizationId, orgId),
+        ),
+      );
+    return rows[0];
+  }
+
+  async findAllEndpoints(
+    orgId: string,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(webhookEndpoints)
+      .where(eq(webhookEndpoints.organizationId, orgId));
+  }
+
+  async findActiveEndpoints(
+    orgId: string,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint[]> {
+    const db = this.getDb(ctx);
+    return db
+      .select()
+      .from(webhookEndpoints)
+      .where(
+        and(
+          eq(webhookEndpoints.organizationId, orgId),
+          eq(webhookEndpoints.isActive, true),
+        ),
+      );
+  }
+
+  async findEndpointsForEvent(
+    eventName: string,
+    orgId: string,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint[]> {
+    const active = await this.findActiveEndpoints(orgId, ctx);
+    // Filter endpoints that subscribe to this event
+    return active.filter((endpoint) => {
+      const events = endpoint.events as string[];
+      return events.includes(eventName) || events.includes("*");
+    });
+  }
+
+  async createEndpoint(
+    data: WebhookEndpointInsert,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(webhookEndpoints).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateEndpoint(
+    id: string,
+    data: Partial<Omit<WebhookEndpointInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(webhookEndpoints)
+      .set(data)
+      .where(eq(webhookEndpoints.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async deleteEndpoint(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .delete(webhookEndpoints)
+      .where(eq(webhookEndpoints.id, id))
+      .returning();
+    return result.length > 0;
+  }
+
+  async activateEndpoint(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint | undefined> {
+    return this.updateEndpoint(id, { isActive: true }, ctx);
+  }
+
+  async deactivateEndpoint(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<WebhookEndpoint | undefined> {
+    return this.updateEndpoint(id, { isActive: false }, ctx);
+  }
+
+  // ─────────────────────────────────────────────────────────────────────────────
+  // Webhook Deliveries
+  // ─────────────────────────────────────────────────────────────────────────────
+
+  async findDeliveryById(
+    id: string,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .select()
+      .from(webhookDeliveries)
+      .where(eq(webhookDeliveries.id, id));
+    return rows[0];
+  }
+
+  async findDeliveriesByEndpointId(
+    endpointId: string,
+    options?: { limit?: number },
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery[]> {
+    const db = this.getDb(ctx);
+    let query = db
+      .select()
+      .from(webhookDeliveries)
+      .where(eq(webhookDeliveries.endpointId, endpointId))
+      .orderBy(desc(webhookDeliveries.createdAt))
+      .$dynamic();
+
+    if (options?.limit !== undefined) {
+      query = query.limit(options.limit);
+    }
+
+    return query;
+  }
+
+  async findPendingDeliveries(ctx?: TxContext): Promise<WebhookDelivery[]> {
+    const db = this.getDb(ctx);
+    const now = new Date();
+
+    return db
+      .select()
+      .from(webhookDeliveries)
+      .where(
+        and(
+          isNull(webhookDeliveries.deliveredAt),
+          isNull(webhookDeliveries.failedAt),
+          or(
+            isNull(webhookDeliveries.nextRetryAt),
+            lte(webhookDeliveries.nextRetryAt, now),
+          ),
+        ),
+      )
+      .orderBy(webhookDeliveries.createdAt);
+  }
+
+  async findFailedDeliveries(
+    endpointId?: string,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery[]> {
+    const db = this.getDb(ctx);
+
+    if (endpointId) {
+      return db
+        .select()
+        .from(webhookDeliveries)
+        .where(
+          and(
+            eq(webhookDeliveries.endpointId, endpointId),
+            sql`${webhookDeliveries.failedAt} IS NOT NULL`,
+          ),
+        )
+        .orderBy(desc(webhookDeliveries.failedAt));
+    }
+
+    return db
+      .select()
+      .from(webhookDeliveries)
+      .where(sql`${webhookDeliveries.failedAt} IS NOT NULL`)
+      .orderBy(desc(webhookDeliveries.failedAt));
+  }
+
+  async createDelivery(
+    data: WebhookDeliveryInsert,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery> {
+    const db = this.getDb(ctx);
+    const rows = await db.insert(webhookDeliveries).values(data).returning();
+    return rows[0]!;
+  }
+
+  async updateDelivery(
+    id: string,
+    data: Partial<Omit<WebhookDeliveryInsert, "id">>,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery | undefined> {
+    const db = this.getDb(ctx);
+    const rows = await db
+      .update(webhookDeliveries)
+      .set(data)
+      .where(eq(webhookDeliveries.id, id))
+      .returning();
+    return rows[0];
+  }
+
+  async markDelivered(
+    id: string,
+    statusCode: number,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery | undefined> {
+    return this.updateDelivery(
+      id,
+      {
+        statusCode,
+        deliveredAt: new Date(),
+        nextRetryAt: null,
+      },
+      ctx,
+    );
+  }
+
+  async markFailed(
+    id: string,
+    statusCode: number | null,
+    nextRetryAt?: Date,
+    ctx?: TxContext,
+  ): Promise<WebhookDelivery | undefined> {
+    const delivery = await this.findDeliveryById(id, ctx);
+    if (!delivery) return undefined;
+
+    const data: Partial<WebhookDeliveryInsert> = {
+      statusCode: statusCode ?? undefined,
+      attemptCount: delivery.attemptCount + 1,
+    };
+
+    if (nextRetryAt) {
+      data.nextRetryAt = nextRetryAt;
+    } else {
+      data.failedAt = new Date();
+      data.nextRetryAt = null;
+    }
+
+    return this.updateDelivery(id, data, ctx);
+  }
+
+  async deleteDelivery(id: string, ctx?: TxContext): Promise<boolean> {
+    const db = this.getDb(ctx);
+    const result = await db
+      .delete(webhookDeliveries)
+      .where(eq(webhookDeliveries.id, id))
+      .returning();
+    return result.length > 0;
+  }
+
+  async deleteDeliveriesByEndpointId(
+    endpointId: string,
+    ctx?: TxContext,
+  ): Promise<void> {
+    const db = this.getDb(ctx);
+    await db
+      .delete(webhookDeliveries)
+      .where(eq(webhookDeliveries.endpointId, endpointId));
+  }
+}

package/src/modules/webhooks/schema.ts

@@ -0,0 +1,56 @@
+import {
+  boolean,
+  index,
+  integer,
+  jsonb,
+  pgTable,
+  text,
+  timestamp,
+  uuid,
+} from "drizzle-orm/pg-core";
+import { organization } from "../../auth/auth-schema.js";
+
+export const webhookEndpoints = pgTable(
+  "webhook_endpoints",
+  {
+    id: uuid("id").defaultRandom().primaryKey(),
+    organizationId: text("organization_id")
+      .notNull()
+      .references(() => organization.id, { onDelete: "cascade" }),
+    url: text("url").notNull(),
+    secret: text("secret").notNull(),
+    events: jsonb("events").$type<string[]>().notNull(),
+    isActive: boolean("is_active").notNull().default(true),
+    metadata: jsonb("metadata").$type<Record<string, unknown>>().default({}),
+  },
+  (table) => ({
+    orgIdx: index("idx_webhook_endpoints_org").on(table.organizationId),
+  }),
+);
+
+/**
+ * Tracks processed incoming webhook events for idempotency.
+ * Prevents double-processing when Stripe (or other providers) retry delivery.
+ */
+export const processedWebhookEvents = pgTable("processed_webhook_events", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  eventId: text("event_id").notNull().unique(),
+  provider: text("provider").notNull(), // "stripe", "paypal", etc.
+  eventType: text("event_type").notNull(),
+  processedAt: timestamp("processed_at", { withTimezone: true }).defaultNow().notNull(),
+});
+
+export const webhookDeliveries = pgTable("webhook_deliveries", {
+  id: uuid("id").defaultRandom().primaryKey(),
+  endpointId: uuid("endpoint_id")
+    .references(() => webhookEndpoints.id)
+    .notNull(),
+  eventName: text("event_name").notNull(),
+  payload: jsonb("payload").notNull(),
+  statusCode: integer("status_code"),
+  attemptCount: integer("attempt_count").notNull().default(0),
+  nextRetryAt: timestamp("next_retry_at", { withTimezone: true }),
+  deliveredAt: timestamp("delivered_at", { withTimezone: true }),
+  failedAt: timestamp("failed_at", { withTimezone: true }),
+  createdAt: timestamp("created_at", { withTimezone: true }).defaultNow().notNull(),
+});