@porulle/core 0.7.0 → 0.8.0

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

@@ -477,3 +477,56 @@ export const generateVariantsRoute = createRoute({
     ...errorResponses,
   },
 });
+
+// ── One-call variant creation (issue #50) ───────────────────────────────────
+
+export const QuickVariantBodySchema = z.object({
+  options: z.record(z.string().min(1), z.string().min(1)).openapi({
+    example: { color: "Red", size: "M" },
+    description: "Axis name → value. Option types/values are upserted inline.",
+  }),
+  sku: z.string().min(1).optional(),
+  barcode: z.string().min(1).optional(),
+}).openapi("QuickVariantRequest");
+
+export const BulkVariantsBodySchema = z.object({
+  axes: z.array(z.object({
+    name: z.string().min(1),
+    values: z.array(z.string().min(1)).min(1),
+  })).openapi({
+    example: [{ name: "color", values: ["Red", "Blue"] }, { name: "size", values: ["S", "M"] }],
+    description: "Matrix axes; an empty array creates one option-less variant.",
+  }),
+  skuPrefix: z.string().min(1).optional(),
+}).openapi("BulkVariantsRequest");
+
+export const quickVariantRoute = createRoute({
+  method: "post",
+  path: "/entities/{id}/variants/quick",
+  tags: ["Catalog"],
+  summary: "Create one sellable variant in a single call (upserts axes, seeds inventory)",
+  request: {
+    params: EntityIdParam,
+    body: { content: { "application/json": { schema: QuickVariantBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponse } }, description: "Variant created and inventory seeded." },
+    200: { content: { "application/json": { schema: DataResponse } }, description: "The combination already existed; the existing variant is returned." },
+    ...errorResponses,
+  },
+});
+
+export const bulkVariantsRoute = createRoute({
+  method: "post",
+  path: "/entities/{id}/variants/bulk",
+  tags: ["Catalog"],
+  summary: "Create a variant matrix in a single call (upserts axes, seeds inventory, skips existing)",
+  request: {
+    params: EntityIdParam,
+    body: { content: { "application/json": { schema: BulkVariantsBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponse } }, description: "Variants created (existing combinations skipped)." },
+    ...errorResponses,
+  },
+});

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

@@ -6,6 +6,10 @@ 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" }),
+  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).",
+  }),
   customerId: z.string().optional().openapi({ example: "customer-uuid-or-user-id" }),
   customerGroupIds: z.array(z.string()).optional(),
   currency: z.string().length(3).optional().openapi({ example: "USD" }),

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

@@ -0,0 +1,72 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+const IdParam = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+
+export const EmailInvoiceBodySchema = z.object({
+  to: z.email().openapi({ example: "customer@example.com" }),
+}).openapi("EmailInvoiceRequest");
+
+const DataResponse = z.object({ data: z.any() }).openapi("DocumentActionResponse");
+
+export const invoicePdfRoute = createRoute({
+  method: "get",
+  path: "/{id}/invoice.pdf",
+  tags: ["Documents"],
+  summary: "Render the order's invoice as PDF (issues a fiscal invoice number on first render)",
+  request: { params: IdParam },
+  responses: {
+    200: {
+      content: { "application/pdf": { schema: z.any().openapi({ type: "string", format: "binary" }) } },
+      description: "The rendered PDF invoice.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const invoiceHtmlRoute = createRoute({
+  method: "get",
+  path: "/{id}/invoice.html",
+  tags: ["Documents"],
+  summary: "Render the order's invoice as HTML",
+  request: { params: IdParam },
+  responses: {
+    200: {
+      content: { "text/html": { schema: z.string() } },
+      description: "The rendered HTML invoice.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const receiptHtmlRoute = createRoute({
+  method: "get",
+  path: "/{id}/receipt.html",
+  tags: ["Documents"],
+  summary: "Render the order's receipt as HTML",
+  request: { params: IdParam },
+  responses: {
+    200: {
+      content: { "text/html": { schema: z.string() } },
+      description: "The rendered HTML receipt.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const emailInvoiceRoute = createRoute({
+  method: "post",
+  path: "/{id}/invoice/email",
+  tags: ["Documents"],
+  summary: "Email the order's invoice via the configured email adapter",
+  request: {
+    params: IdParam,
+    body: { content: { "application/json": { schema: EmailInvoiceBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Invoice emailed." },
+    ...errorResponses,
+  },
+});

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

@@ -39,6 +39,10 @@ const CreateOrderLineItemSchema = z.object({
 
 export const CreateOrderBodySchema = z.object({
   customerId: z.uuid().optional(),
+  idempotencyKey: z.string().min(8).max(255).optional().openapi({
+    example: "pos-sale-8f14e45f-1738312200",
+    description: "Client-supplied retry key. Re-submitting a create with the same key returns the original order instead of creating a duplicate (safe offline-queue replay).",
+  }),
   currency: z.string().min(3).max(3).openapi({ example: "USD" }),
   subtotal: z.number().int().nonnegative().openapi({ example: 2500 }),
   taxTotal: z.number().int().nonnegative().openapi({ example: 200 }),
@@ -140,6 +144,41 @@ export const getOrderFulfillmentsRoute = createRoute({
   },
 });
 
+export const CreateFulfillmentBodySchema = z.object({
+  lineItems: z.array(z.object({
+    orderLineItemId: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+    quantity: z.number().int().positive().openapi({ example: 2 }),
+  })).min(1),
+  carrier: z.string().optional().openapi({ example: "DHL" }),
+  trackingNumber: z.string().optional().openapi({ example: "DHL-123456" }),
+  trackingUrl: z.string().optional().openapi({ example: "https://track.dhl.com/DHL-123456" }),
+  type: z.string().optional().openapi({ example: "physical" }),
+  status: z.string().optional().openapi({ example: "shipped" }),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("CreateFulfillmentRequest");
+
+export const createOrderFulfillmentRoute = createRoute({
+  method: "post",
+  path: "/{id}/fulfillments",
+  tags: ["Orders"],
+  summary: "Record a fulfillment (shipment) for an order",
+  description: "Creates a fulfillment for a subset of the order's line items with optional carrier/tracking details. Supports partial fulfillment (per-line quantities) and multiple fulfillments per order.",
+  request: {
+    params: OrderIdParam,
+    body: {
+      content: { "application/json": { schema: CreateFulfillmentBodySchema } },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: OrderDataResponseSchema } },
+      description: "Fulfillment recorded.",
+    },
+    ...errorResponses,
+  },
+});
+
 export const createOrderRoute = createRoute({
   method: "post",
   path: "/",
@@ -205,6 +244,91 @@ export const captureOrderRoute = createRoute({
   },
 });
 
+export const AddOrderLineItemBodySchema = z.object({
+  entityId: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+  entityType: z.string().min(1).openapi({ example: "product" }),
+  variantId: z.uuid().optional(),
+  sku: z.string().optional(),
+  title: z.string().min(1).openapi({ example: "Ceylon Black Tea 250g" }),
+  quantity: z.number().int().positive().openapi({ example: 1 }),
+  unitPrice: z.number().int().nonnegative().openapi({ example: 1250 }),
+  totalPrice: z.number().int().nonnegative().optional().openapi({ example: 1250 }),
+  taxAmount: z.number().int().nonnegative().optional(),
+  discountAmount: z.number().int().nonnegative().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("AddOrderLineItemRequest");
+
+export const UpdateOrderLineItemBodySchema = z.object({
+  quantity: z.number().int().positive().openapi({ example: 3 }),
+}).openapi("UpdateOrderLineItemRequest");
+
+const OrderLineItemParams = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+  lineItemId: z.uuid().openapi({ example: "660e8400-e29b-41d4-a716-446655440001" }),
+});
+
+export const addOrderLineItemRoute = createRoute({
+  method: "post",
+  path: "/{id}/line-items",
+  tags: ["Orders"],
+  summary: "Add a line item to a placed order",
+  description: "Adds a line item to a non-terminal order and recalculates subtotal/tax/grand totals. Records an audit entry.",
+  request: {
+    params: OrderIdParam,
+    body: {
+      content: { "application/json": { schema: AddOrderLineItemBodySchema } },
+      required: true,
+    },
+  },
+  responses: {
+    201: {
+      content: { "application/json": { schema: OrderDataResponseSchema } },
+      description: "Line item added; updated order returned.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const updateOrderLineItemRoute = createRoute({
+  method: "patch",
+  path: "/{id}/line-items/{lineItemId}",
+  tags: ["Orders"],
+  summary: "Adjust a line item's quantity on a placed order",
+  description: "Changes a line item's quantity on a non-terminal order, scaling line totals/tax and recalculating order totals. Records an audit entry.",
+  request: {
+    params: OrderLineItemParams,
+    body: {
+      content: { "application/json": { schema: UpdateOrderLineItemBodySchema } },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: OrderDataResponseSchema } },
+      description: "Line item updated; updated order returned.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const removeOrderLineItemRoute = createRoute({
+  method: "delete",
+  path: "/{id}/line-items/{lineItemId}",
+  tags: ["Orders"],
+  summary: "Remove a line item from a placed order",
+  description: "Removes a line item from a non-terminal order (at least one line item must remain) and recalculates order totals. Records an audit entry.",
+  request: {
+    params: OrderLineItemParams,
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: OrderDataResponseSchema } },
+      description: "Line item removed; updated order returned.",
+    },
+    ...errorResponses,
+  },
+});
+
 export const changeOrderStatusRoute = createRoute({
   method: "patch",
   path: "/{id}/status",
@@ -227,3 +351,136 @@ export const changeOrderStatusRoute = createRoute({
     ...errorResponses,
   },
 });
+
+// ── Line-level refund policy primitives (issue #52) ─────────────────────────
+
+export const RefundLinesBodySchema = z.object({
+  lines: z.array(z.object({
+    lineItemId: z.uuid(),
+    quantity: z.number().int().min(1),
+  })).min(1),
+  reason: z.string().max(500).optional(),
+}).openapi("RefundLinesRequest");
+
+const RefundParam = z.object({
+  id: z.uuid(),
+  refundId: z.uuid(),
+});
+
+const RefundDataResponse = z.object({ data: z.any() }).openapi("RefundResponse");
+
+export const refundOrderLinesRoute = createRoute({
+  method: "post",
+  path: "/{id}/refunds",
+  tags: ["Orders"],
+  summary: "Refund specific line-item quantities",
+  description: "Enforces per-line refundable quantity and the operator's daily refund cap (policies.refundDailyCap). Records an auditable refund ledger row supporting undo.",
+  request: {
+    params: OrderIdParam,
+    body: { content: { "application/json": { schema: RefundLinesBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: RefundDataResponse } }, description: "Refund recorded." },
+    ...errorResponses,
+  },
+});
+
+export const undoOrderRefundRoute = createRoute({
+  method: "post",
+  path: "/{id}/refunds/{refundId}/undo",
+  tags: ["Orders"],
+  summary: "Undo a refund within the policy window",
+  request: { params: RefundParam },
+  responses: {
+    200: { content: { "application/json": { schema: RefundDataResponse } }, description: "Refund undone." },
+    ...errorResponses,
+  },
+});
+
+export const listOrderRefundsRoute = createRoute({
+  method: "get",
+  path: "/{id}/refunds",
+  tags: ["Orders"],
+  summary: "List an order's refunds",
+  request: { params: OrderIdParam },
+  responses: {
+    200: { content: { "application/json": { schema: RefundDataResponse } }, description: "Refund ledger rows." },
+    ...errorResponses,
+  },
+});
+
+export const refundCapStatusRoute = createRoute({
+  method: "get",
+  path: "/refunds/cap",
+  tags: ["Orders"],
+  summary: "The acting operator's daily refund-cap status",
+  responses: {
+    200: { content: { "application/json": { schema: RefundDataResponse } }, description: "Cap, used-today, and remaining." },
+    ...errorResponses,
+  },
+});
+
+// ── Order notes + activity timeline (issue #56) ─────────────────────────────
+
+export const CreateOrderNoteBodySchema = z.object({
+  body: z.string().min(1).max(2000),
+  pinned: z.boolean().optional(),
+}).openapi("CreateOrderNoteRequest");
+
+const NoteParam = z.object({
+  id: z.uuid(),
+  noteId: z.uuid(),
+});
+
+const NoteDataResponse = z.object({ data: z.any() }).openapi("OrderNoteResponse");
+
+export const createOrderNoteRoute = createRoute({
+  method: "post",
+  path: "/{id}/notes",
+  tags: ["Orders"],
+  summary: "Add an operator note to an order",
+  request: {
+    params: OrderIdParam,
+    body: { content: { "application/json": { schema: CreateOrderNoteBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: NoteDataResponse } }, description: "Note created." },
+    ...errorResponses,
+  },
+});
+
+export const listOrderNotesRoute = createRoute({
+  method: "get",
+  path: "/{id}/notes",
+  tags: ["Orders"],
+  summary: "List an order's notes (pinned first)",
+  request: { params: OrderIdParam },
+  responses: {
+    200: { content: { "application/json": { schema: NoteDataResponse } }, description: "Notes." },
+    ...errorResponses,
+  },
+});
+
+export const deleteOrderNoteRoute = createRoute({
+  method: "delete",
+  path: "/{id}/notes/{noteId}",
+  tags: ["Orders"],
+  summary: "Delete an order note",
+  request: { params: NoteParam },
+  responses: {
+    200: { content: { "application/json": { schema: NoteDataResponse } }, description: "Note deleted." },
+    ...errorResponses,
+  },
+});
+
+export const orderTimelineRoute = createRoute({
+  method: "get",
+  path: "/{id}/timeline",
+  tags: ["Orders"],
+  summary: "Merged activity timeline: status changes + notes + refunds, newest first",
+  request: { params: OrderIdParam },
+  responses: {
+    200: { content: { "application/json": { schema: NoteDataResponse } }, description: "Timeline events." },
+    ...errorResponses,
+  },
+});

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

@@ -57,6 +57,81 @@ export const setBasePriceRoute = createRoute({
   },
 });
 
+export const UpdateModifierBodySchema = z.object({
+  name: z.string().optional(),
+  value: z.number().optional(),
+  priority: z.number().int().optional(),
+  validFrom: z.coerce.date().nullable().optional(),
+  validUntil: z.coerce.date().nullable().optional(),
+  minQuantity: z.number().int().nullable().optional(),
+  maxQuantity: z.number().int().nullable().optional(),
+  metadata: z.record(z.string(), z.unknown()).optional(),
+}).openapi("UpdateModifierRequest");
+
+const ModifierIdParam = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+
+export const listModifiersRoute = createRoute({
+  method: "get",
+  path: "/modifiers",
+  tags: ["Pricing"],
+  summary: "List price modifiers",
+  description: "Lists active and scheduled price modifiers. Filter by entityId, currency, or active=true (currently within validity window).",
+  request: {
+    query: z.object({
+      entityId: z.string().optional(),
+      currency: z.string().optional(),
+      active: z.string().optional().openapi({ example: "true" }),
+    }),
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: PricingResponseSchema } },
+      description: "Price modifiers",
+    },
+    ...errorResponses,
+  },
+});
+
+export const updateModifierRoute = createRoute({
+  method: "patch",
+  path: "/modifiers/{id}",
+  tags: ["Pricing"],
+  summary: "Update a price modifier's value or validity",
+  request: {
+    params: ModifierIdParam,
+    body: {
+      content: { "application/json": { schema: UpdateModifierBodySchema } },
+      required: true,
+    },
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: PricingResponseSchema } },
+      description: "Price modifier updated.",
+    },
+    ...errorResponses,
+  },
+});
+
+export const deleteModifierRoute = createRoute({
+  method: "delete",
+  path: "/modifiers/{id}",
+  tags: ["Pricing"],
+  summary: "Delete a price modifier (end a sale early)",
+  request: {
+    params: ModifierIdParam,
+  },
+  responses: {
+    200: {
+      content: { "application/json": { schema: PricingResponseSchema } },
+      description: "Price modifier deleted.",
+    },
+    ...errorResponses,
+  },
+});
+
 export const createModifierRoute = createRoute({
   method: "post",
   path: "/modifiers",

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

@@ -0,0 +1,93 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+function isValidTimezone(tz: string): boolean {
+  try {
+    new Intl.DateTimeFormat("en-US", { timeZone: tz });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+// Known typed groups. Every field is optional (PATCH is a partial merge) and
+// nullable (null deletes the key). Unknown groups accept any flat JSON object
+// so plugins can namespace their own settings.
+export const GeneralSettingsPatchSchema = z.object({
+  currency: z.string().regex(/^[A-Z]{3}$/, "ISO 4217 uppercase code").nullable().optional(),
+  timezone: z.string().refine(isValidTimezone, "Must be a valid IANA timezone (e.g. Asia/Colombo)").nullable().optional(),
+  locale: z.string().min(2).nullable().optional(),
+}).strict();
+
+export const BrandingSettingsPatchSchema = z.object({
+  storeName: z.string().nullable().optional(),
+  receiptHeader: z.string().nullable().optional(),
+  receiptFooter: z.string().nullable().optional(),
+  logoUrl: z.string().nullable().optional(),
+  address: z.string().nullable().optional(),
+  phone: z.string().nullable().optional(),
+  email: z.string().nullable().optional(),
+  taxId: z.string().nullable().optional(),
+}).strict();
+
+export const PoliciesSettingsPatchSchema = z.record(
+  z.string(),
+  z.union([z.string(), z.number(), z.boolean(), z.null()]),
+);
+
+export const KNOWN_GROUP_SCHEMAS: Record<string, z.ZodTypeAny> = {
+  general: GeneralSettingsPatchSchema,
+  branding: BrandingSettingsPatchSchema,
+  policies: PoliciesSettingsPatchSchema,
+};
+
+const GroupParam = z.object({
+  group: z.string().regex(/^[a-z][a-z0-9_-]*$/).openapi({ example: "branding" }),
+});
+
+const SettingsPatchBodySchema = z
+  .record(z.string(), z.unknown())
+  .openapi("SettingsPatchRequest", {
+    description:
+      "Shallow merge into the group: keys overwrite, null deletes a key. Known groups (general, branding, policies) are validated.",
+  });
+
+const DataResponse = z.object({ data: z.any() }).openapi("SettingsResponse");
+
+export const getAllSettingsRoute = createRoute({
+  method: "get",
+  path: "/",
+  tags: ["Settings"],
+  summary: "Get all settings groups for the organization",
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "All settings groups" },
+    ...errorResponses,
+  },
+});
+
+export const getSettingsGroupRoute = createRoute({
+  method: "get",
+  path: "/{group}",
+  tags: ["Settings"],
+  summary: "Get one settings group",
+  request: { params: GroupParam },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Settings group (empty object if unset)" },
+    ...errorResponses,
+  },
+});
+
+export const patchSettingsGroupRoute = createRoute({
+  method: "patch",
+  path: "/{group}",
+  tags: ["Settings"],
+  summary: "Merge values into a settings group",
+  request: {
+    params: GroupParam,
+    body: { content: { "application/json": { schema: SettingsPatchBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "The merged group value" },
+    ...errorResponses,
+  },
+});