@porulle/core 0.7.0 → 0.9.0

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,12 +144,47 @@ 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: "/",
   tags: ["Orders"],
   summary: "Create a draft / manual order",
-  description: "Operator-created order (phone / POS / manual) with line items and totals, optionally without immediate payment.",
+  description: "Requires `orders:manage`. Creates an operator-entered order (phone / POS / manual); supplied line prices are stored as audited manual overrides.",
   request: {
     body: {
       content: { "application/json": { schema: CreateOrderBodySchema } },
@@ -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: "Requires `orders:manage`. Adds a line item to a non-terminal order, records its supplied price as a manual override, and recalculates totals.",
+  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,
+  },
+});

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

@@ -0,0 +1,164 @@
+import { z, createRoute } from "@hono/zod-openapi";
+import { errorResponses } from "./shared.js";
+
+// ─── Request Schemas ────────────────────────────────────────────────────────
+
+export const CreateShippingZoneBodySchema = z.object({
+  name: z.string().min(1).openapi({ example: "United States" }),
+  countries: z.array(z.string().min(1)).min(1).openapi({ example: ["US"] }),
+  states: z.array(z.string().min(1)).optional().openapi({ example: ["NY", "NJ"] }),
+  priority: z.number().int().optional(),
+  isActive: z.boolean().optional(),
+}).openapi("CreateShippingZoneRequest");
+
+export const UpdateShippingZoneBodySchema = z.object({
+  name: z.string().min(1).optional(),
+  countries: z.array(z.string().min(1)).min(1).optional(),
+  states: z.array(z.string().min(1)).optional(),
+  priority: z.number().int().optional(),
+  isActive: z.boolean().optional(),
+}).openapi("UpdateShippingZoneRequest");
+
+export const CreateShippingRateBodySchema = z.object({
+  zoneId: z.uuid(),
+  name: z.string().min(1).openapi({ example: "Standard" }),
+  amount: z.number().int().nonnegative().openapi({ example: 1500, description: "Flat cost in minor units" }),
+  currency: z.string().length(3).optional().openapi({ example: "USD" }),
+  minSubtotal: z.number().int().nonnegative().optional(),
+  maxSubtotal: z.number().int().nonnegative().optional(),
+  minWeightGrams: z.number().int().nonnegative().optional(),
+  maxWeightGrams: z.number().int().nonnegative().optional(),
+  freeShippingThreshold: z.number().int().nonnegative().optional().openapi({ example: 10000, description: "Subtotal at or above which shipping is free" }),
+  isActive: z.boolean().optional(),
+}).openapi("CreateShippingRateRequest");
+
+export const UpdateShippingRateBodySchema = z.object({
+  name: z.string().min(1).optional(),
+  amount: z.number().int().nonnegative().optional(),
+  currency: z.string().length(3).optional(),
+  minSubtotal: z.number().int().nonnegative().nullable().optional(),
+  maxSubtotal: z.number().int().nonnegative().nullable().optional(),
+  minWeightGrams: z.number().int().nonnegative().nullable().optional(),
+  maxWeightGrams: z.number().int().nonnegative().nullable().optional(),
+  freeShippingThreshold: z.number().int().nonnegative().nullable().optional(),
+  isActive: z.boolean().optional(),
+}).openapi("UpdateShippingRateRequest");
+
+// ─── Shared ─────────────────────────────────────────────────────────────────
+
+const IdParam = z.object({
+  id: z.uuid().openapi({ example: "550e8400-e29b-41d4-a716-446655440000" }),
+});
+
+const DataResponse = z.object({ data: z.any() }).openapi("ShippingConfigResponse");
+
+// ─── Zone Routes ────────────────────────────────────────────────────────────
+
+export const createShippingZoneRoute = createRoute({
+  method: "post",
+  path: "/zones",
+  tags: ["Shipping"],
+  summary: "Create a shipping zone",
+  request: {
+    body: { content: { "application/json": { schema: CreateShippingZoneBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponse } }, description: "Zone created." },
+    ...errorResponses,
+  },
+});
+
+export const listShippingZonesRoute = createRoute({
+  method: "get",
+  path: "/zones",
+  tags: ["Shipping"],
+  summary: "List shipping zones",
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Zones" },
+    ...errorResponses,
+  },
+});
+
+export const updateShippingZoneRoute = createRoute({
+  method: "patch",
+  path: "/zones/{id}",
+  tags: ["Shipping"],
+  summary: "Update a shipping zone",
+  request: {
+    params: IdParam,
+    body: { content: { "application/json": { schema: UpdateShippingZoneBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Zone updated." },
+    ...errorResponses,
+  },
+});
+
+export const deleteShippingZoneRoute = createRoute({
+  method: "delete",
+  path: "/zones/{id}",
+  tags: ["Shipping"],
+  summary: "Delete a shipping zone (and its rates)",
+  request: { params: IdParam },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Zone deleted." },
+    ...errorResponses,
+  },
+});
+
+// ─── Rate Routes ────────────────────────────────────────────────────────────
+
+export const createShippingRateRoute = createRoute({
+  method: "post",
+  path: "/rates",
+  tags: ["Shipping"],
+  summary: "Create a shipping rate in a zone",
+  request: {
+    body: { content: { "application/json": { schema: CreateShippingRateBodySchema } }, required: true },
+  },
+  responses: {
+    201: { content: { "application/json": { schema: DataResponse } }, description: "Rate created." },
+    ...errorResponses,
+  },
+});
+
+export const listShippingRatesRoute = createRoute({
+  method: "get",
+  path: "/rates",
+  tags: ["Shipping"],
+  summary: "List shipping rates",
+  request: {
+    query: z.object({ zoneId: z.string().optional() }),
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Rates" },
+    ...errorResponses,
+  },
+});
+
+export const updateShippingRateRoute = createRoute({
+  method: "patch",
+  path: "/rates/{id}",
+  tags: ["Shipping"],
+  summary: "Update a shipping rate",
+  request: {
+    params: IdParam,
+    body: { content: { "application/json": { schema: UpdateShippingRateBodySchema } }, required: true },
+  },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Rate updated." },
+    ...errorResponses,
+  },
+});
+
+export const deleteShippingRateRoute = createRoute({
+  method: "delete",
+  path: "/rates/{id}",
+  tags: ["Shipping"],
+  summary: "Delete a shipping rate",
+  request: { params: IdParam },
+  responses: {
+    200: { content: { "application/json": { schema: DataResponse } }, description: "Rate deleted." },
+    ...errorResponses,
+  },
+});