@classytic/primitives 0.1.0 → 0.1.1

package/CHANGELOG.md

@@ -3,6 +3,26 @@
 Format based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 adhering to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.1]
+
+### Added
+
+- **`MinorUnits<C>` branded type on `/money`** — wire-format monetary amount
+  (integer minor units, branded with phantom currency) for HTTP/JSON fields
+  where a full `Money` struct is overkill. Erases at runtime; `MinorUnits<'BDT'>`
+  vs `MinorUnits<'USD'>` collide at compile time. Pair with structured `Money`
+  for in-process arithmetic. Constructor: `MinorUnits(amount, currency?)`.
+
+### Changed
+
+- **`/tenant` `contextKey` cascade default** — `resolveTenantConfig({ tenantField: 'branchId' })`
+  now defaults `contextKey` to `'branchId'` instead of `'organizationId'`.
+  When a host renames `tenantField`, their `OperationContext` carries the id
+  under the same key in the overwhelming majority of cases; mirroring the
+  rename is the least-surprise default. Explicit `contextKey` still overrides
+  (set when the doc field and context key genuinely diverge). Existing call
+  sites that supplied both `tenantField` and `contextKey` are unaffected.
+
 ## [0.1.0]
 
 Initial release. Framework-agnostic TypeScript primitives shared across

package/dist/money.d.mts

@@ -1,6 +1,38 @@
 import { CurrencyCode } from "./currency.mjs";
 
 //#region src/money.d.ts
+/**
+ * Wire-format monetary amount: integer minor units, branded with a phantom
+ * currency type so calls like `formatBdt(usdValue)` fail at compile time.
+ *
+ * Use this for HTTP/JSON fields where transmitting a `Money` struct would be
+ * overkill: `interface Order { grandTotal: MinorUnits<'BDT'>; ... }`. Pair
+ * with the structured {@link Money} for in-process arithmetic.
+ *
+ * Erases at runtime — branded types have zero cost.
+ *
+ * @example
+ * type Paisa = MinorUnits<'BDT'>;
+ * type UsdCents = MinorUnits<'USD'>;
+ * const p: Paisa = MinorUnits(489900, 'BDT');
+ * const c: UsdCents = p; // ❌ type error: BDT vs USD
+ */
+declare const __unitBrand: unique symbol;
+declare const __currencyBrand: unique symbol;
+type MinorUnits<C extends string = string> = number & {
+  readonly [__unitBrand]: 'minor';
+  readonly [__currencyBrand]: C;
+};
+/**
+ * Cast a raw number to {@link MinorUnits}. Pass the currency as the second
+ * argument to fix the phantom type. With no second arg, `MinorUnits<string>`
+ * — useful for generic SDK boundaries that don't know the currency yet.
+ *
+ * @example
+ * MinorUnits(489900, 'BDT')   // typed MinorUnits<'BDT'>
+ * MinorUnits(199, 'USD')      // typed MinorUnits<'USD'>
+ */
+declare function MinorUnits<C extends string = string>(amount: number, _currency?: C): MinorUnits<C>;
 /**
  * A monetary amount stored as an integer in the currency's minor unit.
  *
@@ -75,4 +107,4 @@ declare function absMoney(m: Money): Money;
 /** Structural type guard. */
 declare function isMoney(value: unknown): value is Money;
 //#endregion
-export { CurrencyMismatchError, Money, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };
+export { CurrencyMismatchError, MinorUnits, Money, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };

package/dist/money.mjs

@@ -1,5 +1,17 @@
 import { minorUnitFactor } from "./currency.mjs";
 //#region src/money.ts
+/**
+* Cast a raw number to {@link MinorUnits}. Pass the currency as the second
+* argument to fix the phantom type. With no second arg, `MinorUnits<string>`
+* — useful for generic SDK boundaries that don't know the currency yet.
+*
+* @example
+* MinorUnits(489900, 'BDT')   // typed MinorUnits<'BDT'>
+* MinorUnits(199, 'USD')      // typed MinorUnits<'USD'>
+*/
+function MinorUnits(amount, _currency) {
+	return amount;
+}
 var CurrencyMismatchError = class extends Error {
 	name = "CurrencyMismatchError";
 	left;
@@ -128,4 +140,4 @@ function isMoney(value) {
 	return typeof value === "object" && value !== null && typeof value.amount === "number" && Number.isInteger(value.amount) && typeof value.currency === "string";
 }
 //#endregion
-export { CurrencyMismatchError, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };
+export { CurrencyMismatchError, MinorUnits, absMoney, addMoney, compareMoney, equalsMoney, fromMajor, isMoney, isNegativeMoney, isPositiveMoney, isZeroMoney, money, multiplyMoney, negateMoney, subtractMoney, sumMoney, toMajor };

package/dist/tenant.d.mts

@@ -71,7 +71,14 @@ interface TenantConfig {
   /**
    * Which key on `OperationContext` to read the tenant id from.
    *
-   * @default 'organizationId'
+   * Defaults cascade: if omitted, falls back to the caller's `tenantField`
+   * (if supplied), else to `'organizationId'`. Rationale: when a host renames
+   * `tenantField` to e.g. `'branchId'`, their `OperationContext` almost always
+   * carries the value under the same key — so mirroring `tenantField` is the
+   * least-surprise behavior. Override explicitly if the context key diverges
+   * from the document field (e.g. `tenantField: 'branchId'`, `contextKey: 'organizationId'`).
+   *
+   * @default tenantField ?? 'organizationId'
    */
   contextKey?: string;
   /**

package/dist/tenant.mjs

@@ -26,9 +26,11 @@ function resolveTenantConfig(config) {
 	};
 	if (config === true || config === void 0) return { ...DEFAULT_TENANT_CONFIG };
 	const strategy = config.strategy ?? (config.enabled === false ? "none" : "field");
+	const contextKey = config.contextKey ?? config.tenantField ?? DEFAULT_TENANT_CONFIG.contextKey;
 	if (strategy === "none") return {
 		...DEFAULT_TENANT_CONFIG,
 		...config,
+		contextKey,
 		strategy: "none",
 		enabled: false,
 		required: false
@@ -38,6 +40,7 @@ function resolveTenantConfig(config) {
 		return {
 			...DEFAULT_TENANT_CONFIG,
 			...config,
+			contextKey,
 			strategy: "custom",
 			enabled: config.enabled ?? true,
 			resolve: config.resolve
@@ -46,6 +49,7 @@ function resolveTenantConfig(config) {
 	return {
 		...DEFAULT_TENANT_CONFIG,
 		...config,
+		contextKey,
 		strategy: "field",
 		enabled: config.enabled ?? true
 	};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@classytic/primitives",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Framework-agnostic TypeScript primitives shared across Classytic packages — Money, events, pagination, tenant config, and other building blocks.",
   "author": "Classytic",
   "license": "MIT",
@@ -117,11 +117,13 @@
     "test:all": "vitest run",
     "test:watch": "vitest --project unit --project integration",
     "test:smoke": "node tests/smoke/smoke.mjs",
+    "push": "classytic-push",
     "prepublishOnly": "npm run typecheck && npm run test && npm run build && npm run test:smoke",
     "release": "npm run build && npm run typecheck && npm publish --access public"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.9",
+    "@classytic/dev-tools": "^0.2.0",
     "@types/node": "^25.5.0",
     "tsdown": "^0.21.7",
     "typescript": "^5.7.0",