@jaicome/contracts 0.0.73

package/README.md

@@ -0,0 +1,15 @@
+# api
+
+To install dependencies:
+
+```bash
+bun install
+```
+
+To run:
+
+```bash
+bun run index.ts
+```
+
+This project was created using `bun init` in bun v1.2.18. [Bun](https://bun.sh) is a fast all-in-one JavaScript runtime.

package/dist/fulfillment-states.d.mts

@@ -0,0 +1,129 @@
+import { i as FulfillmentState$1 } from "./orders-yFOPRYZw.mjs";
+
+//#region src/fulfillment-states.d.ts
+
+type FulfillmentState = FulfillmentState$1;
+/**
+ * All valid fulfillment states in order
+ *
+ * State Definitions:
+ * - NEW: Customer placed & paid order
+ * - AWAITING_DELIVERY: Merchant accepted delivery order, waiting for delivery provider acceptance
+ * - CONFIRMED: Provider accepted delivery OR non-delivery order accepted by merchant
+ * - READY: [OPTIONAL] Merchant marked order as ready for pickup/delivery
+ * - ON_THE_WAY: Order is in transit (delivery only)
+ * - COMPLETED: Order delivered or picked up
+ * - CANCELLED: Cancelled before fulfillment (terminal)
+ * - FAILED: Fulfillment attempt failed (terminal)
+ * - REFUNDED: Order payment has been refunded (terminal)
+ */
+declare const FulfillmentStateValues: readonly ["NEW", "AWAITING_DELIVERY", "CONFIRMED", "READY", "ON_THE_WAY", "COMPLETED", "CANCELLED", "FAILED", "REFUNDED"];
+/**
+ * Terminal states that cannot transition to any other state
+ */
+declare const TerminalStates: ReadonlySet<FulfillmentState>;
+/**
+ * Actor type for determining which transitions are allowed
+ * - "user": User-initiated actions (merchants, admins)
+ * - "system": System-initiated actions (automated processes, background jobs)
+ */
+type Actor = "user" | "system";
+/**
+ * Checks if a fulfillment state transition is allowed
+ *
+ * @param params - Transition parameters
+ * @param params.from - Current state (null treated as NEW)
+ * @param params.to - Target state to transition to
+ * @param params.actor - Actor type: "user" (default) or "system"
+ * @returns true if transition is allowed, false otherwise
+ *
+ * @example
+ * ```ts
+ * canTransition({ from: "NEW", to: "CONFIRMED", actor: "user" }) // true
+ * canTransition({ from: "NEW", to: "FAILED", actor: "user" }) // false (users cannot set FAILED)
+ * canTransition({ from: "NEW", to: "FAILED", actor: "system" }) // true
+ * canTransition({ from: "COMPLETED", to: "NEW" }) // false (COMPLETED is terminal)
+ * canTransition({ from: null, to: "CONFIRMED" }) // true (null treated as NEW)
+ * ```
+ */
+declare function canTransition(params: {
+  from: FulfillmentState | null;
+  to: FulfillmentState;
+  actor?: Actor;
+}): boolean;
+/**
+ * Asserts that a fulfillment state transition is allowed
+ * Throws an error if the transition is not allowed
+ *
+ * @param params - Transition parameters (same as canTransition)
+ * @throws Error if transition is not allowed
+ *
+ * @example
+ * ```ts
+ * assertCanTransition({ from: "NEW", to: "CONFIRMED" }) // ok
+ * assertCanTransition({ from: "COMPLETED", to: "NEW" }) // throws Error
+ * ```
+ */
+declare function assertCanTransition(params: {
+  from: FulfillmentState | null;
+  to: FulfillmentState;
+  actor?: Actor;
+}): void;
+/**
+ * Gets all allowed transitions from a given state for a specific actor
+ *
+ * @param from - Current state (null treated as NEW)
+ * @param actor - Actor type (defaults to "user")
+ * @returns Array of allowed next states
+ *
+ * @example
+ * ```ts
+ * getAllowedTransitions("NEW", "user") // ["AWAITING_DELIVERY", "CONFIRMED", "READY", "ON_THE_WAY", "COMPLETED", "CANCELLED"]
+ * getAllowedTransitions("NEW", "system") // ["AWAITING_DELIVERY", "CONFIRMED", "READY", "ON_THE_WAY", "COMPLETED", "CANCELLED", "FAILED"]
+ * getAllowedTransitions("COMPLETED") // ["REFUNDED"]
+ * getAllowedTransitions("CANCELLED") // []
+ * ```
+ */
+declare function getAllowedTransitions(from: FulfillmentState | null, actor?: Actor): FulfillmentState[];
+/**
+ * Gets all allowed transitions for a given state for the user actor
+ * Convenience function that calls getAllowedTransitions with actor="user"
+ *
+ * @param from - Current state (null treated as NEW)
+ * @returns Array of allowed next states for user-initiated actions
+ *
+ * @example
+ * ```ts
+ * getAllowedUserTransitions("CONFIRMED") // ["READY", "ON_THE_WAY", "COMPLETED", "REFUNDED"]
+ * ```
+ */
+declare function getAllowedUserTransitions(from: FulfillmentState | null): FulfillmentState[];
+/**
+ * Checks if a state is a terminal state
+ *
+ * @param state - The state to check
+ * @returns true if the state is terminal (no further transitions possible)
+ *
+ * @example
+ * ```ts
+ * isTerminalState("COMPLETED") // false
+ * isTerminalState("CANCELLED") // true
+ * isTerminalState("REFUNDED") // true
+ * ```
+ */
+declare function isTerminalState(state: FulfillmentState): boolean;
+/**
+ * Namespace containing all fulfillment state machine operations
+ * Provides a unified API for state machine functionality
+ */
+declare const FulfillmentStateMachine: {
+  readonly canTransition: typeof canTransition;
+  readonly assertCanTransition: typeof assertCanTransition;
+  readonly getAllowedTransitions: typeof getAllowedTransitions;
+  readonly getAllowedUserTransitions: typeof getAllowedUserTransitions;
+  readonly isTerminalState: typeof isTerminalState;
+  readonly values: readonly ["NEW", "AWAITING_DELIVERY", "CONFIRMED", "READY", "ON_THE_WAY", "COMPLETED", "CANCELLED", "FAILED", "REFUNDED"];
+  readonly terminalStates: ReadonlySet<"NEW" | "AWAITING_DELIVERY" | "CONFIRMED" | "READY" | "ON_THE_WAY" | "COMPLETED" | "CANCELLED" | "FAILED" | "REFUNDED">;
+};
+//#endregion
+export { Actor, FulfillmentState, FulfillmentStateMachine, FulfillmentStateValues, TerminalStates, assertCanTransition, canTransition, getAllowedTransitions, getAllowedUserTransitions, isTerminalState };

package/dist/fulfillment-states.mjs

@@ -0,0 +1,225 @@
+//#region src/fulfillment-states.ts
+/**
+* All valid fulfillment states in order
+*
+* State Definitions:
+* - NEW: Customer placed & paid order
+* - AWAITING_DELIVERY: Merchant accepted delivery order, waiting for delivery provider acceptance
+* - CONFIRMED: Provider accepted delivery OR non-delivery order accepted by merchant
+* - READY: [OPTIONAL] Merchant marked order as ready for pickup/delivery
+* - ON_THE_WAY: Order is in transit (delivery only)
+* - COMPLETED: Order delivered or picked up
+* - CANCELLED: Cancelled before fulfillment (terminal)
+* - FAILED: Fulfillment attempt failed (terminal)
+* - REFUNDED: Order payment has been refunded (terminal)
+*/
+const FulfillmentStateValues = [
+	"NEW",
+	"AWAITING_DELIVERY",
+	"CONFIRMED",
+	"READY",
+	"ON_THE_WAY",
+	"COMPLETED",
+	"CANCELLED",
+	"FAILED",
+	"REFUNDED"
+];
+/**
+* Terminal states that cannot transition to any other state
+*/
+const TerminalStates = new Set([
+	"CANCELLED",
+	"FAILED",
+	"REFUNDED"
+]);
+/**
+* Allowed forward transitions for user-initiated actions
+* Users cannot directly set FAILED state
+*/
+const AllowedUserTransitions = {
+	NEW: new Set([
+		"AWAITING_DELIVERY",
+		"CONFIRMED",
+		"READY",
+		"ON_THE_WAY",
+		"COMPLETED",
+		"CANCELLED"
+	]),
+	AWAITING_DELIVERY: new Set([
+		"CONFIRMED",
+		"READY",
+		"ON_THE_WAY",
+		"COMPLETED",
+		"CANCELLED"
+	]),
+	CONFIRMED: new Set([
+		"READY",
+		"ON_THE_WAY",
+		"COMPLETED",
+		"REFUNDED"
+	]),
+	READY: new Set(["ON_THE_WAY", "COMPLETED"]),
+	ON_THE_WAY: new Set(["COMPLETED", "REFUNDED"]),
+	COMPLETED: new Set(["REFUNDED"]),
+	CANCELLED: /* @__PURE__ */ new Set(),
+	FAILED: /* @__PURE__ */ new Set(),
+	REFUNDED: /* @__PURE__ */ new Set()
+};
+/**
+* Allowed forward transitions for system-initiated actions
+* System can additionally set FAILED at any non-terminal state
+*/
+const AllowedSystemTransitions = {
+	NEW: new Set([
+		"AWAITING_DELIVERY",
+		"CONFIRMED",
+		"READY",
+		"ON_THE_WAY",
+		"COMPLETED",
+		"CANCELLED",
+		"FAILED"
+	]),
+	AWAITING_DELIVERY: new Set([
+		"CONFIRMED",
+		"READY",
+		"ON_THE_WAY",
+		"COMPLETED",
+		"CANCELLED",
+		"FAILED"
+	]),
+	CONFIRMED: new Set([
+		"READY",
+		"ON_THE_WAY",
+		"COMPLETED",
+		"REFUNDED",
+		"FAILED"
+	]),
+	READY: new Set([
+		"ON_THE_WAY",
+		"COMPLETED",
+		"FAILED"
+	]),
+	ON_THE_WAY: new Set([
+		"COMPLETED",
+		"REFUNDED",
+		"FAILED"
+	]),
+	COMPLETED: new Set(["REFUNDED"]),
+	CANCELLED: /* @__PURE__ */ new Set(),
+	FAILED: /* @__PURE__ */ new Set(),
+	REFUNDED: /* @__PURE__ */ new Set()
+};
+/**
+* Checks if a fulfillment state transition is allowed
+*
+* @param params - Transition parameters
+* @param params.from - Current state (null treated as NEW)
+* @param params.to - Target state to transition to
+* @param params.actor - Actor type: "user" (default) or "system"
+* @returns true if transition is allowed, false otherwise
+*
+* @example
+* ```ts
+* canTransition({ from: "NEW", to: "CONFIRMED", actor: "user" }) // true
+* canTransition({ from: "NEW", to: "FAILED", actor: "user" }) // false (users cannot set FAILED)
+* canTransition({ from: "NEW", to: "FAILED", actor: "system" }) // true
+* canTransition({ from: "COMPLETED", to: "NEW" }) // false (COMPLETED is terminal)
+* canTransition({ from: null, to: "CONFIRMED" }) // true (null treated as NEW)
+* ```
+*/
+function canTransition(params) {
+	const { from, to, actor = "user" } = params;
+	if (from && from === to) return false;
+	const current = from ?? "NEW";
+	if (TerminalStates.has(current)) return false;
+	if (actor === "user" && to === "FAILED") return false;
+	return (actor === "system" ? AllowedSystemTransitions : AllowedUserTransitions)[current].has(to);
+}
+/**
+* Asserts that a fulfillment state transition is allowed
+* Throws an error if the transition is not allowed
+*
+* @param params - Transition parameters (same as canTransition)
+* @throws Error if transition is not allowed
+*
+* @example
+* ```ts
+* assertCanTransition({ from: "NEW", to: "CONFIRMED" }) // ok
+* assertCanTransition({ from: "COMPLETED", to: "NEW" }) // throws Error
+* ```
+*/
+function assertCanTransition(params) {
+	if (!canTransition(params)) {
+		const { from, to, actor = "user" } = params;
+		const readableFrom = from ?? "NEW";
+		throw new Error(`Invalid fulfillment transition: ${readableFrom} -> ${to} (actor=${actor})`);
+	}
+}
+/**
+* Gets all allowed transitions from a given state for a specific actor
+*
+* @param from - Current state (null treated as NEW)
+* @param actor - Actor type (defaults to "user")
+* @returns Array of allowed next states
+*
+* @example
+* ```ts
+* getAllowedTransitions("NEW", "user") // ["AWAITING_DELIVERY", "CONFIRMED", "READY", "ON_THE_WAY", "COMPLETED", "CANCELLED"]
+* getAllowedTransitions("NEW", "system") // ["AWAITING_DELIVERY", "CONFIRMED", "READY", "ON_THE_WAY", "COMPLETED", "CANCELLED", "FAILED"]
+* getAllowedTransitions("COMPLETED") // ["REFUNDED"]
+* getAllowedTransitions("CANCELLED") // []
+* ```
+*/
+function getAllowedTransitions(from, actor) {
+	const current = from ?? "NEW";
+	if (TerminalStates.has(current)) return [];
+	const allowedNext = (actor === "system" ? AllowedSystemTransitions : AllowedUserTransitions)[current];
+	return Array.from(allowedNext);
+}
+/**
+* Gets all allowed transitions for a given state for the user actor
+* Convenience function that calls getAllowedTransitions with actor="user"
+*
+* @param from - Current state (null treated as NEW)
+* @returns Array of allowed next states for user-initiated actions
+*
+* @example
+* ```ts
+* getAllowedUserTransitions("CONFIRMED") // ["READY", "ON_THE_WAY", "COMPLETED", "REFUNDED"]
+* ```
+*/
+function getAllowedUserTransitions(from) {
+	return getAllowedTransitions(from, "user");
+}
+/**
+* Checks if a state is a terminal state
+*
+* @param state - The state to check
+* @returns true if the state is terminal (no further transitions possible)
+*
+* @example
+* ```ts
+* isTerminalState("COMPLETED") // false
+* isTerminalState("CANCELLED") // true
+* isTerminalState("REFUNDED") // true
+* ```
+*/
+function isTerminalState(state) {
+	return TerminalStates.has(state);
+}
+/**
+* Namespace containing all fulfillment state machine operations
+* Provides a unified API for state machine functionality
+*/
+const FulfillmentStateMachine = {
+	canTransition,
+	assertCanTransition,
+	getAllowedTransitions,
+	getAllowedUserTransitions,
+	isTerminalState,
+	values: FulfillmentStateValues,
+	terminalStates: TerminalStates
+};
+
+//#endregion
+export { FulfillmentStateMachine, FulfillmentStateValues, TerminalStates, assertCanTransition, canTransition, getAllowedTransitions, getAllowedUserTransitions, isTerminalState };