@heavybit/ecommerce-contracts 0.0.0-stage → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (130) hide show
  1. package/README.md +158 -2
  2. package/dist/cjs/app.js +38 -0
  3. package/dist/cjs/app.js.map +1 -0
  4. package/dist/cjs/bindings.js +127 -0
  5. package/dist/cjs/bindings.js.map +1 -0
  6. package/dist/cjs/events/audit.js +26 -0
  7. package/dist/cjs/events/audit.js.map +1 -0
  8. package/dist/cjs/events/auth.js +68 -0
  9. package/dist/cjs/events/auth.js.map +1 -0
  10. package/dist/cjs/events/base.js +99 -0
  11. package/dist/cjs/events/base.js.map +1 -0
  12. package/dist/cjs/events/cart.js +15 -0
  13. package/dist/cjs/events/cart.js.map +1 -0
  14. package/dist/cjs/events/catalog.js +24 -0
  15. package/dist/cjs/events/catalog.js.map +1 -0
  16. package/dist/cjs/events/gateway.js +24 -0
  17. package/dist/cjs/events/gateway.js.map +1 -0
  18. package/dist/cjs/events/index.js +131 -0
  19. package/dist/cjs/events/index.js.map +1 -0
  20. package/dist/cjs/events/media.js +17 -0
  21. package/dist/cjs/events/media.js.map +1 -0
  22. package/dist/cjs/events/notification.js +43 -0
  23. package/dist/cjs/events/notification.js.map +1 -0
  24. package/dist/cjs/events/order.js +45 -0
  25. package/dist/cjs/events/order.js.map +1 -0
  26. package/dist/cjs/events/payment.js +34 -0
  27. package/dist/cjs/events/payment.js.map +1 -0
  28. package/dist/cjs/events/security.js +36 -0
  29. package/dist/cjs/events/security.js.map +1 -0
  30. package/dist/cjs/events/shipping.js +25 -0
  31. package/dist/cjs/events/shipping.js.map +1 -0
  32. package/dist/cjs/events/store.js +25 -0
  33. package/dist/cjs/events/store.js.map +1 -0
  34. package/dist/cjs/events/usage.js +17 -0
  35. package/dist/cjs/events/usage.js.map +1 -0
  36. package/dist/cjs/identity.js +50 -0
  37. package/dist/cjs/identity.js.map +1 -0
  38. package/dist/cjs/index.js +27 -0
  39. package/dist/cjs/index.js.map +1 -0
  40. package/dist/cjs/package.json +1 -0
  41. package/dist/cjs/permissions.js +10 -0
  42. package/dist/cjs/permissions.js.map +1 -0
  43. package/dist/cjs/scopes.js +57 -0
  44. package/dist/cjs/scopes.js.map +1 -0
  45. package/dist/esm/app.js +35 -0
  46. package/dist/esm/app.js.map +1 -0
  47. package/dist/esm/bindings.js +115 -0
  48. package/dist/esm/bindings.js.map +1 -0
  49. package/dist/esm/events/audit.js +23 -0
  50. package/dist/esm/events/audit.js.map +1 -0
  51. package/dist/esm/events/auth.js +65 -0
  52. package/dist/esm/events/auth.js.map +1 -0
  53. package/dist/esm/events/base.js +90 -0
  54. package/dist/esm/events/base.js.map +1 -0
  55. package/dist/esm/events/cart.js +12 -0
  56. package/dist/esm/events/cart.js.map +1 -0
  57. package/dist/esm/events/catalog.js +21 -0
  58. package/dist/esm/events/catalog.js.map +1 -0
  59. package/dist/esm/events/gateway.js +21 -0
  60. package/dist/esm/events/gateway.js.map +1 -0
  61. package/dist/esm/events/index.js +100 -0
  62. package/dist/esm/events/index.js.map +1 -0
  63. package/dist/esm/events/media.js +14 -0
  64. package/dist/esm/events/media.js.map +1 -0
  65. package/dist/esm/events/notification.js +40 -0
  66. package/dist/esm/events/notification.js.map +1 -0
  67. package/dist/esm/events/order.js +42 -0
  68. package/dist/esm/events/order.js.map +1 -0
  69. package/dist/esm/events/payment.js +31 -0
  70. package/dist/esm/events/payment.js.map +1 -0
  71. package/dist/esm/events/security.js +33 -0
  72. package/dist/esm/events/security.js.map +1 -0
  73. package/dist/esm/events/shipping.js +22 -0
  74. package/dist/esm/events/shipping.js.map +1 -0
  75. package/dist/esm/events/store.js +22 -0
  76. package/dist/esm/events/store.js.map +1 -0
  77. package/dist/esm/events/usage.js +14 -0
  78. package/dist/esm/events/usage.js.map +1 -0
  79. package/dist/esm/identity.js +47 -0
  80. package/dist/esm/identity.js.map +1 -0
  81. package/dist/esm/index.js +11 -0
  82. package/dist/esm/index.js.map +1 -0
  83. package/dist/esm/package.json +1 -0
  84. package/dist/esm/permissions.js +7 -0
  85. package/dist/esm/permissions.js.map +1 -0
  86. package/dist/esm/scopes.js +52 -0
  87. package/dist/esm/scopes.js.map +1 -0
  88. package/dist/types/app.d.ts +40 -0
  89. package/dist/types/app.d.ts.map +1 -0
  90. package/dist/types/bindings.d.ts +88 -0
  91. package/dist/types/bindings.d.ts.map +1 -0
  92. package/dist/types/events/audit.d.ts +86 -0
  93. package/dist/types/events/audit.d.ts.map +1 -0
  94. package/dist/types/events/auth.d.ts +357 -0
  95. package/dist/types/events/auth.d.ts.map +1 -0
  96. package/dist/types/events/base.d.ts +108 -0
  97. package/dist/types/events/base.d.ts.map +1 -0
  98. package/dist/types/events/cart.d.ts +37 -0
  99. package/dist/types/events/cart.d.ts.map +1 -0
  100. package/dist/types/events/catalog.d.ts +126 -0
  101. package/dist/types/events/catalog.d.ts.map +1 -0
  102. package/dist/types/events/gateway.d.ts +77 -0
  103. package/dist/types/events/gateway.d.ts.map +1 -0
  104. package/dist/types/events/index.d.ts +4333 -0
  105. package/dist/types/events/index.d.ts.map +1 -0
  106. package/dist/types/events/media.d.ts +51 -0
  107. package/dist/types/events/media.d.ts.map +1 -0
  108. package/dist/types/events/notification.d.ts +270 -0
  109. package/dist/types/events/notification.d.ts.map +1 -0
  110. package/dist/types/events/order.d.ts +289 -0
  111. package/dist/types/events/order.d.ts.map +1 -0
  112. package/dist/types/events/payment.d.ts +228 -0
  113. package/dist/types/events/payment.d.ts.map +1 -0
  114. package/dist/types/events/security.d.ts +201 -0
  115. package/dist/types/events/security.d.ts.map +1 -0
  116. package/dist/types/events/shipping.d.ts +91 -0
  117. package/dist/types/events/shipping.d.ts.map +1 -0
  118. package/dist/types/events/store.d.ts +134 -0
  119. package/dist/types/events/store.d.ts.map +1 -0
  120. package/dist/types/events/usage.d.ts +59 -0
  121. package/dist/types/events/usage.d.ts.map +1 -0
  122. package/dist/types/identity.d.ts +22 -0
  123. package/dist/types/identity.d.ts.map +1 -0
  124. package/dist/types/index.d.ts +11 -0
  125. package/dist/types/index.d.ts.map +1 -0
  126. package/dist/types/permissions.d.ts +7 -0
  127. package/dist/types/permissions.d.ts.map +1 -0
  128. package/dist/types/scopes.d.ts +57 -0
  129. package/dist/types/scopes.d.ts.map +1 -0
  130. package/package.json +44 -4
@@ -0,0 +1,59 @@
1
+ /** Billable usage events (pay-as-you-sell billing): read by the billing ledger. */
2
+ import { z } from '@heavybit/shared-lib';
3
+ /** Usage routing keys (published by notification-service and shipping-service). */
4
+ export declare const USAGE_KEYS: {
5
+ readonly sms: {
6
+ readonly sent: "usage.sms.sent";
7
+ };
8
+ readonly delivery: {
9
+ readonly booked: "usage.delivery.booked";
10
+ };
11
+ };
12
+ /** v1 payload schemas of the usage events. */
13
+ export declare const USAGE_EVENTS: {
14
+ readonly "usage.sms.sent": z.ZodObject<{
15
+ companyId: z.ZodString;
16
+ } & {
17
+ messageId: z.ZodString;
18
+ segments: z.ZodNumber;
19
+ cost: z.ZodString;
20
+ currency: z.ZodLiteral<"KES">;
21
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
22
+ companyId: z.ZodString;
23
+ } & {
24
+ messageId: z.ZodString;
25
+ segments: z.ZodNumber;
26
+ cost: z.ZodString;
27
+ currency: z.ZodLiteral<"KES">;
28
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
29
+ companyId: z.ZodString;
30
+ } & {
31
+ messageId: z.ZodString;
32
+ segments: z.ZodNumber;
33
+ cost: z.ZodString;
34
+ currency: z.ZodLiteral<"KES">;
35
+ }, z.ZodTypeAny, "passthrough">>;
36
+ readonly "usage.delivery.booked": z.ZodObject<{
37
+ companyId: z.ZodString;
38
+ } & {
39
+ shipmentId: z.ZodString;
40
+ provider: z.ZodString;
41
+ fee: z.ZodString;
42
+ currency: z.ZodLiteral<"KES">;
43
+ }, "passthrough", z.ZodTypeAny, z.objectOutputType<{
44
+ companyId: z.ZodString;
45
+ } & {
46
+ shipmentId: z.ZodString;
47
+ provider: z.ZodString;
48
+ fee: z.ZodString;
49
+ currency: z.ZodLiteral<"KES">;
50
+ }, z.ZodTypeAny, "passthrough">, z.objectInputType<{
51
+ companyId: z.ZodString;
52
+ } & {
53
+ shipmentId: z.ZodString;
54
+ provider: z.ZodString;
55
+ fee: z.ZodString;
56
+ currency: z.ZodLiteral<"KES">;
57
+ }, z.ZodTypeAny, "passthrough">>;
58
+ };
59
+ //# sourceMappingURL=usage.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../../src/events/usage.ts"],"names":[],"mappings":"AAAA,mFAAmF;AACnF,OAAO,EAAE,CAAC,EAAE,MAAM,sBAAsB,CAAC;AAGzC,mFAAmF;AACnF,eAAO,MAAM,UAAU;;;;;;;CAGb,CAAC;AAEX,8CAA8C;AAC9C,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAGf,CAAC"}
@@ -0,0 +1,22 @@
1
+ /** Domain separator mixed into every gateway identity signature of this app. */
2
+ export declare const GATEWAY_IDENTITY_DOMAIN: "ecommerce-gateway-identity:v2";
3
+ /** Header carrying the active company id (signed). Maps to `AuthUser.scopes.company`. */
4
+ export declare const COMPANY_ID_HEADER: "x-company-id";
5
+ /** Header carrying the active company slug (signed). Maps to `AuthUser.attrs.companySlug`. */
6
+ export declare const COMPANY_SLUG_HEADER: "x-company-slug";
7
+ /**
8
+ * The app's identity protocol: generic identity headers plus the signed company headers.
9
+ *
10
+ * @example app.use(authenticateFromGateway({ protocol: ecommerceIdentityProtocol, secret: config.GATEWAY_SIGNING_SECRET }))
11
+ */
12
+ export declare const ecommerceIdentityProtocol: import("@heavybit/shared-lib").IdentityProtocol;
13
+ /**
14
+ * Step-up scopes (§6.4). `singleUse` proofs are consumed by the gateway on first use. Each sensitive
15
+ * route declares one of these, and the gateway route map must declare the same.
16
+ *
17
+ * @example router.post('/payouts/destination', requireStepUp('payout-destination'), controller.update)
18
+ */
19
+ export declare const ecommerceStepUpScopes: Readonly<Record<"role-assign" | "role-permissions" | "staff-remove" | "payment-config" | "payout-destination" | "refund-large" | "customer-export" | "domain-change" | "company-close" | "api-key-issue" | "approval-decide" | "company-status" | "ledger-adjust" | "support-access" | "user-security" | "dlq-replay", Readonly<import("@heavybit/shared-lib").StepUpScopeDefinition>>>;
20
+ /** One step-up scope name. */
21
+ export type EcommerceStepUpScope = keyof typeof ecommerceStepUpScopes;
22
+ //# sourceMappingURL=identity.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"identity.d.ts","sourceRoot":"","sources":["../../src/identity.ts"],"names":[],"mappings":"AAOA,gFAAgF;AAChF,eAAO,MAAM,uBAAuB,EAAG,+BAAwC,CAAC;AAEhF,yFAAyF;AACzF,eAAO,MAAM,iBAAiB,EAAG,cAAuB,CAAC;AACzD,8FAA8F;AAC9F,eAAO,MAAM,mBAAmB,EAAG,gBAAyB,CAAC;AAE7D;;;;GAIG;AACH,eAAO,MAAM,yBAAyB,iDAIpC,CAAC;AAEH;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,yXAiBhC,CAAC;AAEH,8BAA8B;AAC9B,MAAM,MAAM,oBAAoB,GAAG,MAAM,OAAO,qBAAqB,CAAC"}
@@ -0,0 +1,11 @@
1
+ /**
2
+ * `@heavybit/ecommerce-contracts` (D40): the e-commerce app's settings, identity and scope bindings,
3
+ * step-up scopes and event catalogue, built on `@heavybit/shared-lib`. No business logic.
4
+ */
5
+ export * from './app.js';
6
+ export * from './scopes.js';
7
+ export * from './identity.js';
8
+ export * from './permissions.js';
9
+ export * from './bindings.js';
10
+ export * from './events/index.js';
11
+ //# sourceMappingURL=index.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,cAAc,UAAU,CAAC;AACzB,cAAc,aAAa,CAAC;AAC5B,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,eAAe,CAAC;AAC9B,cAAc,mBAAmB,CAAC"}
@@ -0,0 +1,7 @@
1
+ /**
2
+ * E-commerce permission names (D40). Phases 4 and 6 add the full catalogue here (and seed it in
3
+ * auth-admin-service); services import names from this module instead of writing literals.
4
+ */
5
+ /** Held by anyone who may approve or reject two-person approval requests (§7.4), on top of the operation's own permission. */
6
+ export declare const APPROVAL_DECIDE_PERMISSION: "approval:decide";
7
+ //# sourceMappingURL=permissions.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/permissions.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,8HAA8H;AAC9H,eAAO,MAAM,0BAA0B,EAAG,iBAA0B,CAAC"}
@@ -0,0 +1,57 @@
1
+ /**
2
+ * E-commerce row-scope bindings (spec §5). Every repository over tenant data is built on shared-lib
3
+ * `ScopedRepository` with one of these, so no query can leave out its scope column.
4
+ *
5
+ * - {@link companyScope}: a company's own rows (`company_id`), value from the gateway-signed company header (TEN-1/TEN-2).
6
+ * - {@link customerScope}: a shopper's own rows (`user_id`) across shops (TEN-8).
7
+ * - {@link platformScope}: cross-company reads for platform operators only (TEN-8).
8
+ */
9
+ import type { AuthUser } from '@heavybit/shared-lib';
10
+ import { OwnerScope } from '@heavybit/shared-lib/database';
11
+ /** Database column that carries the tenant on every company-owned table. */
12
+ export declare const COMPANY_COLUMN: "company_id";
13
+ /** Database column that carries the owning shopper on customer-owned rows. */
14
+ export declare const CUSTOMER_COLUMN: "user_id";
15
+ /** Key of the company in `AuthUser.scopes` and in a consumer's restored message scope. */
16
+ export declare const COMPANY_SCOPE_KEY: "company";
17
+ /** Prefix shared by every platform permission (e.g. `platform:company:read`). */
18
+ export declare const PLATFORM_PERMISSION_PREFIX: "platform:";
19
+ /**
20
+ * Company scope. The context is `{ companyId }`, taken from the gateway-signed company header
21
+ * (`x-company-id`, see {@link ecommerceIdentityProtocol}) — never from a request body.
22
+ *
23
+ * @example new ProductRepository(db, products, companyScope).findById({ companyId }, id)
24
+ */
25
+ export declare const companyScope: import("@heavybit/shared-lib/database").ScopeDefinition<"companyId">;
26
+ /**
27
+ * Customer (owner) scope: the shopper's own rows. The context is `{ ownerId: user.id }`.
28
+ *
29
+ * @example new CustomerOrderRepository(db, orders, customerScope).findMany({ ownerId: req.user.id })
30
+ */
31
+ export declare const customerScope: OwnerScope;
32
+ /**
33
+ * True for the platform super admin or anyone holding a `platform:*` permission.
34
+ *
35
+ * @example isPlatformOperator(req.user)
36
+ */
37
+ export declare function isPlatformOperator(user: Pick<AuthUser, 'isSuperAdmin' | 'permissions'>): boolean;
38
+ /**
39
+ * Platform scope over `company_id`. Grants come only from `platformScope.authorize(req.user)`, which
40
+ * throws 403 `PLATFORM_SCOPE_DENIED` unless {@link isPlatformOperator} approves. Routes still check
41
+ * their specific permission with `requirePermission`.
42
+ *
43
+ * @example new CompanyOrderRepository(db, orders, platformScope).findMany(platformScope.authorize(req.user))
44
+ */
45
+ export declare const platformScope: import("@heavybit/shared-lib/database").PlatformScopeDefinition<Pick<AuthUser, "isSuperAdmin" | "permissions">>;
46
+ /**
47
+ * Restores the company scope from a tenant event payload for `MessageConsumer.subscribe({ scopeFrom })`
48
+ * (TEN-7). The result is directly usable as a {@link companyScope} context.
49
+ *
50
+ * @example scopeFrom: companyScopeFrom, handler: ({ data, scope }) => service.onPaid(scope!, data)
51
+ */
52
+ export declare function companyScopeFrom(data: {
53
+ companyId?: string | null;
54
+ }): {
55
+ companyId: string | null | undefined;
56
+ };
57
+ //# sourceMappingURL=scopes.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"scopes.d.ts","sourceRoot":"","sources":["../../src/scopes.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AACH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,sBAAsB,CAAC;AACrD,OAAO,EAAoC,UAAU,EAAE,MAAM,+BAA+B,CAAC;AAE7F,4EAA4E;AAC5E,eAAO,MAAM,cAAc,EAAG,YAAqB,CAAC;AACpD,8EAA8E;AAC9E,eAAO,MAAM,eAAe,EAAG,SAAkB,CAAC;AAClD,0FAA0F;AAC1F,eAAO,MAAM,iBAAiB,EAAG,SAAkB,CAAC;AACpD,iFAAiF;AACjF,eAAO,MAAM,0BAA0B,EAAG,WAAoB,CAAC;AAE/D;;;;;GAKG;AACH,eAAO,MAAM,YAAY,sEAAoF,CAAC;AAE9G;;;;GAIG;AACH,eAAO,MAAM,aAAa,YAAgE,CAAC;AAE3F;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,CAAC,QAAQ,EAAE,cAAc,GAAG,aAAa,CAAC,GAAG,OAAO,CAEhG;AAED;;;;;;GAMG;AACH,eAAO,MAAM,aAAa,iHAIxB,CAAC;AAEH;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE;IAAE,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;CAAE,GAAG;IAAE,SAAS,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAA;CAAE,CAE9G"}
package/package.json CHANGED
@@ -1,6 +1,46 @@
1
1
  {
2
2
  "name": "@heavybit/ecommerce-contracts",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.2.1",
4
+ "description": "The e-commerce app's shared contracts: app settings, identity and scope bindings, step-up scopes, event catalogue and v1 payload schemas. Built on @heavybit/shared-lib; no business logic.",
5
+ "license": "MIT",
6
+ "type": "module",
7
+ "main": "./dist/cjs/index.js",
8
+ "module": "./dist/esm/index.js",
9
+ "types": "./dist/types/index.d.ts",
10
+ "files": [
11
+ "dist",
12
+ "README.md"
13
+ ],
14
+ "sideEffects": false,
15
+ "publishConfig": {
16
+ "access": "public"
17
+ },
18
+ "exports": {
19
+ ".": {
20
+ "types": "./dist/types/index.d.ts",
21
+ "import": "./dist/esm/index.js",
22
+ "require": "./dist/cjs/index.js"
23
+ },
24
+ "./package.json": "./package.json"
25
+ },
26
+ "scripts": {
27
+ "clean": "rm -rf dist",
28
+ "build": "npm run clean && tsc -p tsconfig.esm.json && tsc -p tsconfig.cjs.json && tsc -p tsconfig.types.json && node scripts/write-dist-package-types.mjs",
29
+ "test": "jest --runInBand",
30
+ "typecheck": "tsc --noEmit",
31
+ "prepublishOnly": "npm test && npm run build"
32
+ },
33
+ "dependencies": {
34
+ "@heavybit/shared-lib": "^2.7.1"
35
+ },
36
+ "devDependencies": {
37
+ "@types/jest": "^29.5.14",
38
+ "@types/node": "^22.10.0",
39
+ "jest": "^29.7.0",
40
+ "ts-jest": "^29.4.6",
41
+ "typescript": "^5.7.2"
42
+ },
43
+ "engines": {
44
+ "node": "^22.23.4 || >=24.22.1"
45
+ }
46
+ }