@b1-road/types 0.1.0-alpha.0 → 0.1.0-alpha.1

package/README.md

@@ -27,6 +27,7 @@ Ships dual ESM/CJS builds with type declarations. Zero runtime dependencies.
 | Entities | The resource shapes returned on the wire (business units, members, roles, permissions, …). |
 | Inputs | The request-body shapes the API accepts. |
 | Permissions | The `action:subject` permission algebra and its constants. |
+| Webhooks | Webhook event types, per-event payloads, and the delivery envelope (`RoadWebhookEvent`, `RoadWebhookPayloads`, `ROAD_WEBHOOK_EVENT_TYPES`). |
 | `@b1-road/types/iam` | IAM control-plane types (scopes, assignments, authorization, sessions). |
 
 ```ts
@@ -36,13 +37,17 @@ const baseUrl = `${ROAD_API_URLS.production}/api/${ROAD_API_CONTRACT}`;
 // → https://api.road.app/api/alpha
 ```
 
-## Why a shared package
+## A contract package — the API is a consumer too
 
 Every wire type, permission constant, and hosted URL has exactly one definition.
-SDKs import them; they never re-declare. If a binding needs a shape this package
-doesn't yet expose, it contributes the shape back here in the same change — so
-the React, Nest, and Laravel definitions can never drift. This is the
-load-bearing principle of the multi-SDK ecosystem.
+SDKs import them; they never re-declare. **The Road API depends on this package
+as well** — not as "an SDK the API consumes," but as the contract both sides
+agree on: the API (the producer) declares the wire shapes here and conforms its
+DTOs to them, while the SDKs (the consumers) read the same shapes. The dependency
+direction `API → @b1-road/types` is correct and intended. If a binding or the API
+needs a shape this package doesn't yet expose, it contributes the shape back here
+in the same change — so the API, React, Nest, and Laravel definitions can never
+drift. This is the load-bearing principle of the ecosystem.
 
 ## Versioning
 

package/dist/iam.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/iam.ts"],"sourcesContent":["/**\n * IAM control-plane wire types. These describe the shapes Road's IAM API\n * speaks: scopes, assignments, authorization checks, effective permissions,\n * token exchange, and sessions.\n *\n * They live behind a subpath (`@b1-road/types/iam`) so the React SDK — which\n * never needs the control-plane — doesn't pay for them in its tree-shaken\n * bundle. The Nest SDK imports from here directly.\n */\n\nimport type { RoadPermission } from \"./permissions\";\n\n/** Scope shape. Three flavors today; platforms may register more over time. */\nexport type ScopeType = \"system\" | \"business_unit\" | \"platform\";\n\n/** Subjects the IAM engine can authorize. `service` covers M2M; `api_key` is legacy. */\nexport type SubjectType = \"user\" | \"service\" | \"api_key\";\n\nexport interface Scope {\n  id: string;\n  type: ScopeType;\n  externalId: string | null;\n  parentScopeId: string | null;\n  parentScope?: {\n    id: string;\n    type: ScopeType;\n    externalId: string | null;\n  } | null;\n  metadata: Record<string, unknown>;\n  createdAt: string;\n  updatedAt?: string;\n}\n\nexport interface CreateScopeInput {\n  type: ScopeType;\n  externalId?: string | null;\n  parentScopeId?: string | null;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface Assignment {\n  id: string;\n  subjectType: SubjectType;\n  subjectId: string;\n  roleId: string;\n  scopeId: string;\n  grantedBy: string;\n  grantedAt: string;\n  expiresAt: string | null;\n}\n\nexport interface CreateAssignmentInput {\n  subjectType: SubjectType;\n  subjectId: string;\n  roleId: string;\n  scopeId: string;\n  expiresAt?: string | null;\n}\n\nexport interface AuthorizeInput {\n  subjectType: SubjectType;\n  subjectId: string;\n  scopeId: string;\n  /** Either a single permission string (`\"read:Member\"`) or the wildcard. */\n  permission: RoadPermission | (string & {});\n}\n\nexport interface AuthorizeResult {\n  allowed: boolean;\n  reason: string;\n  /** Scope chain that was walked during evaluation (target → ... → root). */\n  evaluatedScopes: string[];\n}\n\nexport interface AuthorizeBatchInput {\n  subjectType: SubjectType;\n  subjectId: string;\n  scopeId: string;\n  permissions: Array<RoadPermission | (string & {})>;\n}\n\nexport interface AuthorizeBatchResult {\n  results: Array<{ permission: string; allowed: boolean }>;\n}\n\nexport interface EffectivePermissionsResult {\n  /** Expanded permissions; `manage:X` has been expanded into the CRUD set. */\n  permissions: string[];\n}\n\nexport interface Session {\n  id: string;\n  deviceName: string;\n  ipAddress: string | null;\n  userAgent?: string;\n  provider: string;\n  lastUsedAt: string;\n  createdAt: string;\n  current: boolean;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}
+{"version":3,"sources":["../src/iam.ts"],"sourcesContent":["/**\n * IAM control-plane wire types. These describe the shapes Road's IAM API\n * speaks: scopes, assignments, authorization checks, effective permissions,\n * token exchange, and sessions.\n *\n * They live behind a subpath (`@b1-road/types/iam`) so the React SDK — which\n * never needs the control-plane — doesn't pay for them in its tree-shaken\n * bundle. The Nest SDK imports from here directly.\n */\n\nimport type { RoadPermission } from \"./permissions\";\n\n/** Scope shape. Three flavors today; platforms may register more over time. */\nexport type ScopeType = \"system\" | \"business_unit\" | \"platform\";\n\n/** Subjects the IAM engine can authorize. `service` covers M2M; `api_key` is legacy. */\nexport type SubjectType = \"user\" | \"service\" | \"api_key\";\n\nexport interface Scope {\n  id: string;\n  type: ScopeType;\n  externalId: string | null;\n  parentScopeId: string | null;\n  parentScope?: {\n    id: string;\n    type: ScopeType;\n    externalId: string | null;\n  } | null;\n  metadata: Record<string, unknown>;\n  createdAt: string;\n  updatedAt?: string;\n}\n\nexport interface CreateScopeInput {\n  type: ScopeType;\n  externalId?: string | null;\n  parentScopeId?: string | null;\n  metadata?: Record<string, unknown>;\n}\n\nexport interface Assignment {\n  id: string;\n  subjectType: SubjectType;\n  subjectId: string;\n  roleId: string;\n  scopeId: string;\n  grantedBy: string;\n  grantedAt: string;\n  expiresAt: string | null;\n}\n\nexport interface CreateAssignmentInput {\n  subjectType: SubjectType;\n  subjectId: string;\n  roleId: string;\n  scopeId: string;\n  expiresAt?: string | null;\n}\n\nexport interface AuthorizeInput {\n  subjectType: SubjectType;\n  subjectId: string;\n  scopeId: string;\n  /** Either a single permission string (`\"read:Member\"`) or the wildcard. */\n  permission: RoadPermission | (string & {});\n}\n\nexport interface AuthorizeResult {\n  allowed: boolean;\n  reason: string;\n}\n\nexport interface AuthorizeBatchInput {\n  subjectType: SubjectType;\n  subjectId: string;\n  scopeId: string;\n  permissions: Array<RoadPermission | (string & {})>;\n}\n\nexport interface AuthorizeBatchResult {\n  results: Array<{ permission: string; allowed: boolean }>;\n}\n\nexport interface EffectivePermissionsResult {\n  /** Expanded permissions; `manage:X` has been expanded into the CRUD set. */\n  permissions: string[];\n}\n\nexport interface Session {\n  id: string;\n  deviceName: string;\n  ipAddress: string | null;\n  userAgent?: string;\n  provider: string;\n  lastUsedAt: string;\n  createdAt: string;\n  current: boolean;\n}\n"],"mappings":";;;;;;;;;;;;;;;;AAAA;AAAA;","names":[]}

package/dist/iam.d.cts

@@ -61,8 +61,6 @@ interface AuthorizeInput {
 interface AuthorizeResult {
     allowed: boolean;
     reason: string;
-    /** Scope chain that was walked during evaluation (target → ... → root). */
-    evaluatedScopes: string[];
 }
 interface AuthorizeBatchInput {
     subjectType: SubjectType;

package/dist/iam.d.ts

@@ -61,8 +61,6 @@ interface AuthorizeInput {
 interface AuthorizeResult {
     allowed: boolean;
     reason: string;
-    /** Scope chain that was walked during evaluation (target → ... → root). */
-    evaluatedScopes: string[];
 }
 interface AuthorizeBatchInput {
     subjectType: SubjectType;

package/dist/index.cjs

@@ -24,6 +24,7 @@ __export(src_exports, {
   ROAD_API_URLS: () => ROAD_API_URLS,
   ROAD_CORE_ACTIONS: () => ROAD_CORE_ACTIONS,
   ROAD_CORE_SUBJECTS: () => ROAD_CORE_SUBJECTS,
+  ROAD_WEBHOOK_EVENT_TYPES: () => ROAD_WEBHOOK_EVENT_TYPES,
   ROAD_WILDCARD_PERMISSION: () => ROAD_WILDCARD_PERMISSION
 });
 module.exports = __toCommonJS(src_exports);
@@ -55,12 +56,26 @@ var ROAD_CORE_SUBJECTS = [
   "Invitation"
 ];
 var ROAD_WILDCARD_PERMISSION = "*";
+
+// src/webhooks.ts
+var ROAD_WEBHOOK_EVENT_TYPES = [
+  "organization.invitation.created",
+  "organization.invitation.accepted",
+  "organization.invitation.rejected",
+  "organization.invitation.cancelled",
+  "organization.member.joined",
+  "organization.member.suspended",
+  "organization.member.reinstated",
+  "organization.member.removed",
+  "organization.member.role-changed"
+];
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   ROAD_API_CONTRACT,
   ROAD_API_URLS,
   ROAD_CORE_ACTIONS,
   ROAD_CORE_SUBJECTS,
+  ROAD_WEBHOOK_EVENT_TYPES,
   ROAD_WILDCARD_PERMISSION
 });
 //# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/index.ts","../src/api-contract.ts","../src/api-urls.ts","../src/permissions.ts"],"sourcesContent":["export * from \"./api-contract\";\nexport * from \"./api-urls\";\nexport * from \"./entities\";\nexport * from \"./inputs\";\nexport * from \"./permissions\";\n","/**\n * The Road API **contract version** — the major boundary of the HTTP wire\n * surface. The Road API mounts every route under `/api/<contract>`, and every\n * SDK builds its base path as `${host}/api/${ROAD_API_CONTRACT}`.\n *\n * This is the single source of truth for that value. The Road API imports it\n * for its global prefix; the in-repo clients (admin, tester) and the published\n * SDKs read it from here. It is **not** environment configuration — it is\n * identical in every environment and changes only by a deliberate edit when the\n * wire contract makes a breaking change: `alpha` → `v1` → `v2`.\n *\n * Promoting this from `alpha` to `v1` is the trigger to take the SDKs to their\n * first stable `1.0.0`. See `docs/plans/14-sdk-publishing-and-versioning.md`.\n */\nexport const ROAD_API_CONTRACT = \"alpha\" as const;\n\nexport type RoadApiContract = typeof ROAD_API_CONTRACT;\n","/**\n * Road's hosted API base URLs. SDKs default to ROAD_API_URLS.production; the\n * sandbox URL is the deployed Road sandbox (override via the SDK's apiBaseUrl\n * config if you're running against a different environment, eg. local dev or\n * a private staging cluster).\n *\n * If the deployed sandbox hostname changes, update this constant — it's the\n * single source of truth every SDK reads from.\n */\nexport const ROAD_API_URLS = {\n  production: \"https://api.road.app\",\n  sandbox: \"https://api.road-sandbox.b1.app\",\n} as const;\n\nexport type RoadEnvironment = keyof typeof ROAD_API_URLS;\n","/**\n * Road IAM permission algebra. Permissions are `${action}:${subject}` strings;\n * the wildcard `\"*\"` short-circuits to true for every action in a scope.\n *\n * The widget catalog calls into actions and subjects Road ships by default\n * (the union types below). Platforms can declare their own actions and\n * subjects in their IAM catalog — those flow through useCan as plain strings,\n * still type-safe via `RoadPermission | (string & {})` in the React SDK.\n */\n\n/**\n * The CRUD verbs Road's IAM engine recognizes, plus `manage` which the\n * engine expands server-side into the full CRUD set for the same subject\n * (`manage:Member` ⇒ also `create|read|update|delete:Member` in the\n * effective-permissions response).\n *\n * Platforms can register their own actions (`approve`, `submit`, `list`, …)\n * — those flow through useCan as plain strings (the `(string & {})` part\n * of PermissionInput in the React SDK), still type-safe via that escape.\n */\nexport type RoadAction = \"create\" | \"read\" | \"update\" | \"delete\" | \"manage\";\n\n/**\n * Built-in subjects Road's own permissions cover. Mirrors the subjects\n * registered in the API's `Subjects` constant\n * (apps/api/src/modules/iam/authorization/constants/subjects.ts), limited\n * to the subjects user-facing widgets actually surface:\n *\n *   - BusinessUnit: system-level — create new BUs\n *   - BUDashboard: BU-level — read a BU's detail page\n *   - BUSettings: BU-level — edit a BU's settings\n *   - Member, Role, Permission, Invitation: BU-level CRUD\n *\n * Admin / platform-engineer subjects (System, Platform, AdminUser,\n * PlatformIdentity, …) are not exposed here — they belong to a future\n * developer-facing widget (and admin SDK), not the customer-facing toolkit.\n *\n * Platform-specific subjects (eg. A4L's `Agent`) are not enumerated —\n * platforms register them at runtime under their own scope, and useCan's\n * `(string & {})` accepts them without complaint.\n */\nexport type RoadCoreSubject =\n  | \"BusinessUnit\"\n  | \"BUDashboard\"\n  | \"BUSettings\"\n  | \"Member\"\n  | \"Role\"\n  | \"Permission\"\n  | \"Invitation\";\n\n/** `${action}:${Subject}` for the core set, plus the wildcard. */\nexport type RoadPermission = `${RoadAction}:${RoadCoreSubject}` | \"*\";\n\n/** Runtime array of the core actions — handy for iteration or validation. */\nexport const ROAD_CORE_ACTIONS = [\n  \"create\",\n  \"read\",\n  \"update\",\n  \"delete\",\n  \"manage\",\n] as const satisfies readonly RoadAction[];\n\n/** Runtime array of the core subjects — handy for iteration or validation. */\nexport const ROAD_CORE_SUBJECTS = [\n  \"BusinessUnit\",\n  \"BUDashboard\",\n  \"BUSettings\",\n  \"Member\",\n  \"Role\",\n  \"Permission\",\n  \"Invitation\",\n] as const satisfies readonly RoadCoreSubject[];\n\n/** The wildcard permission string. Use this instead of literal \"*\" for grep-ability. */\nexport const ROAD_WILDCARD_PERMISSION = \"*\" as const;\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACcO,IAAM,oBAAoB;;;ACL1B,IAAM,gBAAgB;AAAA,EAC3B,YAAY;AAAA,EACZ,SAAS;AACX;;;AC0CO,IAAM,oBAAoB;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,qBAAqB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,2BAA2B;","names":[]}
+{"version":3,"sources":["../src/index.ts","../src/api-contract.ts","../src/api-urls.ts","../src/permissions.ts","../src/webhooks.ts"],"sourcesContent":["export * from \"./api-contract\";\nexport * from \"./api-urls\";\nexport * from \"./entities\";\nexport * from \"./inputs\";\nexport * from \"./permissions\";\nexport * from \"./webhooks\";\n","/**\n * The Road API **contract version** — the major boundary of the HTTP wire\n * surface. The Road API mounts every route under `/api/<contract>`, and every\n * SDK builds its base path as `${host}/api/${ROAD_API_CONTRACT}`.\n *\n * This is the single source of truth for that value. The Road API imports it\n * for its global prefix; the in-repo clients (admin, tester) and the published\n * SDKs read it from here. It is **not** environment configuration — it is\n * identical in every environment and changes only by a deliberate edit when the\n * wire contract makes a breaking change: `alpha` → `v1` → `v2`.\n *\n * Promoting this from `alpha` to `v1` is the trigger to take the SDKs to their\n * first stable `1.0.0`. See `docs/plans/14-sdk-publishing-and-versioning.md`.\n */\nexport const ROAD_API_CONTRACT = \"alpha\" as const;\n\nexport type RoadApiContract = typeof ROAD_API_CONTRACT;\n","/**\n * Road's hosted API base URLs. SDKs default to ROAD_API_URLS.production; the\n * sandbox URL is the deployed Road sandbox (override via the SDK's apiBaseUrl\n * config if you're running against a different environment, eg. local dev or\n * a private staging cluster).\n *\n * If the deployed sandbox hostname changes, update this constant — it's the\n * single source of truth every SDK reads from.\n */\nexport const ROAD_API_URLS = {\n  production: \"https://api.road.app\",\n  sandbox: \"https://api.road-sandbox.b1.app\",\n} as const;\n\nexport type RoadEnvironment = keyof typeof ROAD_API_URLS;\n","/**\n * Road IAM permission algebra. Permissions are `${action}:${subject}` strings;\n * the wildcard `\"*\"` short-circuits to true for every action in a scope.\n *\n * The widget catalog calls into actions and subjects Road ships by default\n * (the union types below). Platforms can declare their own actions and\n * subjects in their IAM catalog — those flow through useCan as plain strings,\n * still type-safe via `RoadPermission | (string & {})` in the React SDK.\n */\n\n/**\n * The CRUD verbs Road's IAM engine recognizes, plus `manage` which the\n * engine expands server-side into the full CRUD set for the same subject\n * (`manage:Member` ⇒ also `create|read|update|delete:Member` in the\n * effective-permissions response).\n *\n * Platforms can register their own actions (`approve`, `submit`, `list`, …)\n * — those flow through useCan as plain strings (the `(string & {})` part\n * of PermissionInput in the React SDK), still type-safe via that escape.\n */\nexport type RoadAction = \"create\" | \"read\" | \"update\" | \"delete\" | \"manage\";\n\n/**\n * Built-in subjects Road's own permissions cover. Mirrors the subjects\n * registered in the API's `Subjects` constant\n * (apps/api/src/modules/iam/authorization/constants/subjects.ts), limited\n * to the subjects user-facing widgets actually surface:\n *\n *   - BusinessUnit: system-level — create new BUs\n *   - BUDashboard: BU-level — read a BU's detail page\n *   - BUSettings: BU-level — edit a BU's settings\n *   - Member, Role, Permission, Invitation: BU-level CRUD\n *\n * Admin / platform-engineer subjects (System, Platform, AdminUser,\n * PlatformIdentity, …) are not exposed here — they belong to a future\n * developer-facing widget (and admin SDK), not the customer-facing toolkit.\n *\n * Platform-specific subjects (eg. A4L's `Agent`) are not enumerated —\n * platforms register them at runtime under their own scope, and useCan's\n * `(string & {})` accepts them without complaint.\n */\nexport type RoadCoreSubject =\n  | \"BusinessUnit\"\n  | \"BUDashboard\"\n  | \"BUSettings\"\n  | \"Member\"\n  | \"Role\"\n  | \"Permission\"\n  | \"Invitation\";\n\n/** `${action}:${Subject}` for the core set, plus the wildcard. */\nexport type RoadPermission = `${RoadAction}:${RoadCoreSubject}` | \"*\";\n\n/** Runtime array of the core actions — handy for iteration or validation. */\nexport const ROAD_CORE_ACTIONS = [\n  \"create\",\n  \"read\",\n  \"update\",\n  \"delete\",\n  \"manage\",\n] as const satisfies readonly RoadAction[];\n\n/** Runtime array of the core subjects — handy for iteration or validation. */\nexport const ROAD_CORE_SUBJECTS = [\n  \"BusinessUnit\",\n  \"BUDashboard\",\n  \"BUSettings\",\n  \"Member\",\n  \"Role\",\n  \"Permission\",\n  \"Invitation\",\n] as const satisfies readonly RoadCoreSubject[];\n\n/** The wildcard permission string. Use this instead of literal \"*\" for grep-ability. */\nexport const ROAD_WILDCARD_PERMISSION = \"*\" as const;\n","/**\n * Road webhook events — the canonical wire contract every SDK builds on.\n *\n * The event-type strings and `data` payloads mirror exactly what the Road API\n * delivers: the `event` and `data` fields of the webhook POST body, and the\n * `X-Road-Event` header. SDKs that receive webhooks import from here and never\n * redefine them (SDK DX Bar principle 11 — one source of truth).\n *\n * Only the public `organization.*` events are listed; internal/experimental\n * event namespaces are intentionally excluded from the SDK surface.\n */\n\n/** Payload for every `organization.invitation.*` event. */\nexport interface InvitationWebhookData {\n  businessUnitId: string;\n  invitationId: string;\n  email: string;\n}\n\n/** Payload for `organization.member.{joined,suspended,reinstated,removed}`. */\nexport interface MemberWebhookData {\n  businessUnitId: string;\n  memberId: string;\n  userId: string;\n}\n\n/** Payload for `organization.member.role-changed`. */\nexport interface MemberRoleChangedWebhookData extends MemberWebhookData {\n  roleId: string;\n  action: \"assigned\" | \"revoked\";\n}\n\n/** Maps each webhook event type to the shape of its `data` payload. */\nexport interface RoadWebhookPayloads {\n  \"organization.invitation.created\": InvitationWebhookData;\n  \"organization.invitation.accepted\": InvitationWebhookData;\n  \"organization.invitation.rejected\": InvitationWebhookData;\n  \"organization.invitation.cancelled\": InvitationWebhookData;\n  \"organization.member.joined\": MemberWebhookData;\n  \"organization.member.suspended\": MemberWebhookData;\n  \"organization.member.reinstated\": MemberWebhookData;\n  \"organization.member.removed\": MemberWebhookData;\n  \"organization.member.role-changed\": MemberRoleChangedWebhookData;\n}\n\n/** Every webhook event type the Road API can deliver. */\nexport type RoadWebhookEventType = keyof RoadWebhookPayloads;\n\n/**\n * The exact envelope the Road API POSTs to a registered webhook URL —\n * mirrors the delivered body `{ id, event, timestamp, data }`.\n */\nexport interface RoadWebhookEvent<\n  T extends RoadWebhookEventType = RoadWebhookEventType,\n> {\n  /** Unique delivery id — also sent as the `X-Road-Delivery-Id` header. */\n  id: string;\n  /** The event type — also sent as the `X-Road-Event` header. */\n  event: T;\n  /** ISO-8601 timestamp of the delivery. */\n  timestamp: string;\n  /** Event-specific payload. */\n  data: RoadWebhookPayloads[T];\n}\n\n/**\n * Runtime list of every webhook event type — handy for registering a\n * subscription to \"all events\". `satisfies` guarantees no typo'd or\n * stale entry slips in.\n */\nexport const ROAD_WEBHOOK_EVENT_TYPES = [\n  \"organization.invitation.created\",\n  \"organization.invitation.accepted\",\n  \"organization.invitation.rejected\",\n  \"organization.invitation.cancelled\",\n  \"organization.member.joined\",\n  \"organization.member.suspended\",\n  \"organization.member.reinstated\",\n  \"organization.member.removed\",\n  \"organization.member.role-changed\",\n] as const satisfies readonly RoadWebhookEventType[];\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;;;ACcO,IAAM,oBAAoB;;;ACL1B,IAAM,gBAAgB;AAAA,EAC3B,YAAY;AAAA,EACZ,SAAS;AACX;;;AC0CO,IAAM,oBAAoB;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,qBAAqB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,2BAA2B;;;ACJjC,IAAM,2BAA2B;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;","names":[]}

package/dist/index.d.cts

@@ -33,7 +33,7 @@ declare const ROAD_API_URLS: {
 type RoadEnvironment = keyof typeof ROAD_API_URLS;
 
 type BUStatus = "active" | "suspended" | "archived";
-type MemberStatus = "active" | "suspended" | "pending";
+type MemberStatus = "active" | "suspended" | "removed";
 interface CurrentUser {
     id: string;
     name: string;
@@ -96,7 +96,7 @@ interface Invitation {
     email: string;
     roleId: string;
     roleName: string;
-    status: "pending" | "accepted" | "expired" | "cancelled";
+    status: "pending" | "accepted" | "expired" | "cancelled" | "rejected";
     invitedAt: string;
     expiresAt: string;
 }
@@ -106,7 +106,9 @@ interface Role {
     description: string;
     permissions: string[];
     isSystem: boolean;
-    memberCount: number;
+    /** Count of role assignments (users + service principals + groups). */
+    assignmentCount: number;
+    createdAt: string;
 }
 interface Permission {
     id: string;
@@ -115,19 +117,42 @@ interface Permission {
     description: string;
     /** Subject group (e.g. "Member", "Role", "BusinessUnit") used to group in the picker. */
     category: string;
+    scopeId: string;
+    createdAt: string;
 }
 /**
- * Effective permissions for the current user, keyed by business-unit ID.
- * A value of `["*"]` (ROAD_WILDCARD_PERMISSION) grants every action in that BU.
+ * Effective permissions for the current user, keyed by business-unit ID, as the
+ * **SDK** exposes them — each grant flattened to an `"action:subject"` string
+ * (`["*"]` grants every action in that BU). This is the client-side convenience
+ * shape; the raw wire form is `ScopePermissions` / `ScopePermissionsBulk` below,
+ * which the HTTP client maps into this.
  */
 type MyPermissions = Record<string, string[]>;
 /**
- * Cursor-paginated list response. The API issues opaque base64-url cursors
- * the client treats as opaque — no parsing or arithmetic on the SDK side.
+ * A single effective-permission grant exactly as the API returns it on the
+ * wire: an `action`/`subject` pair. Wildcards are returned as-is
+ * (`{ action: "*", subject: "*" }`), not enumerated.
+ */
+interface PermissionTuple {
+    action: string;
+    subject: string;
+}
+/** Wire shape of `GET /me/permissions?scope=<scopeId>` (single scope). */
+interface ScopePermissions {
+    permissions: PermissionTuple[];
+}
+/**
+ * Wire shape of `GET /me/permissions?scopes=<id>,<id>,…` — effective
+ * permissions keyed by scope id (the SDK's fan-in for multi-BU users).
+ */
+type ScopePermissionsBulk = Record<string, PermissionTuple[]>;
+/**
+ * Cursor-pagination metadata. The API issues opaque base64-url cursors the
+ * client treats as opaque — no parsing or arithmetic on the SDK side.
  * `cursor` is null when no further page exists; `hasMore` is the canonical
  * "more rows after this page" signal, redundant with `cursor !== null`.
  */
-interface PageInfo {
+interface Pagination {
     /** Opaque cursor for the next page. Null when this is the last page. */
     cursor: string | null;
     /** True iff there is at least one row past this page. */
@@ -136,13 +161,15 @@ interface PageInfo {
     totalCount: number;
 }
 /**
- * Generic paged response shape returned from listing endpoints with
- * cursor pagination (members, roles, invitations). Convertible 1:1 to
- * React Query's useInfiniteQuery `pageParam` flow via `pageInfo.cursor`.
+ * Canonical paged response shape for every list endpoint. Mirrors the API's
+ * universal `{ data }` envelope — the rows live under `data` (the same key
+ * as every single-resource response), with cursor `pagination` as a
+ * top-level sibling. Convertible 1:1 to React Query's useInfiniteQuery
+ * `pageParam` flow via `pagination.cursor`.
  */
 interface PaginatedList<T> {
-    items: T[];
-    pageInfo: PageInfo;
+    data: T[];
+    pagination: Pagination;
 }
 /**
  * Input shape for any paginated list call. Both fields are optional —
@@ -150,7 +177,7 @@ interface PaginatedList<T> {
  * (currently 20).
  */
 interface PaginationInput {
-    /** Opaque cursor from a previous `pageInfo.cursor`. Omit for the first page. */
+    /** Opaque cursor from a previous response's `pagination.cursor`. Omit for the first page. */
     cursor?: string;
     /** Page size. Default 20, max 100 (server-enforced). */
     limit?: number;
@@ -163,19 +190,19 @@ interface CreateBusinessUnitInput {
 }
 interface UpdateBusinessUnitInput {
     name?: string;
-    slug?: string;
+    joinCode?: string | null;
     memberLimit?: number | null;
 }
 interface CreateRoleInput {
     name: string;
-    description?: string;
+    description?: string | null;
     permissions: string[];
     /** Source role ID when "clone from existing"; informational only. */
     cloneFromRoleId?: string;
 }
 interface UpdateRoleInput {
     name?: string;
-    description?: string;
+    description?: string | null;
     permissions?: string[];
 }
 interface CreateInvitationInput {
@@ -183,4 +210,67 @@ interface CreateInvitationInput {
     roleId: string;
 }
 
-export { type BUStatus, type BusinessUnitDetail, type BusinessUnitSummary, type CreateBusinessUnitInput, type CreateInvitationInput, type CreateRoleInput, type CurrentUser, type Invitation, type Member, type MemberStatus, type Membership, type MyBusinessUnits, type MyPermissions, type PageInfo, type PaginatedList, type PaginationInput, type PendingInvitation, type Permission, ROAD_API_CONTRACT, ROAD_API_URLS, type RoadApiContract, type RoadEnvironment, type Role, type RoleRef, type UpdateBusinessUnitInput, type UpdateRoleInput };
+/**
+ * Road webhook events — the canonical wire contract every SDK builds on.
+ *
+ * The event-type strings and `data` payloads mirror exactly what the Road API
+ * delivers: the `event` and `data` fields of the webhook POST body, and the
+ * `X-Road-Event` header. SDKs that receive webhooks import from here and never
+ * redefine them (SDK DX Bar principle 11 — one source of truth).
+ *
+ * Only the public `organization.*` events are listed; internal/experimental
+ * event namespaces are intentionally excluded from the SDK surface.
+ */
+/** Payload for every `organization.invitation.*` event. */
+interface InvitationWebhookData {
+    businessUnitId: string;
+    invitationId: string;
+    email: string;
+}
+/** Payload for `organization.member.{joined,suspended,reinstated,removed}`. */
+interface MemberWebhookData {
+    businessUnitId: string;
+    memberId: string;
+    userId: string;
+}
+/** Payload for `organization.member.role-changed`. */
+interface MemberRoleChangedWebhookData extends MemberWebhookData {
+    roleId: string;
+    action: "assigned" | "revoked";
+}
+/** Maps each webhook event type to the shape of its `data` payload. */
+interface RoadWebhookPayloads {
+    "organization.invitation.created": InvitationWebhookData;
+    "organization.invitation.accepted": InvitationWebhookData;
+    "organization.invitation.rejected": InvitationWebhookData;
+    "organization.invitation.cancelled": InvitationWebhookData;
+    "organization.member.joined": MemberWebhookData;
+    "organization.member.suspended": MemberWebhookData;
+    "organization.member.reinstated": MemberWebhookData;
+    "organization.member.removed": MemberWebhookData;
+    "organization.member.role-changed": MemberRoleChangedWebhookData;
+}
+/** Every webhook event type the Road API can deliver. */
+type RoadWebhookEventType = keyof RoadWebhookPayloads;
+/**
+ * The exact envelope the Road API POSTs to a registered webhook URL —
+ * mirrors the delivered body `{ id, event, timestamp, data }`.
+ */
+interface RoadWebhookEvent<T extends RoadWebhookEventType = RoadWebhookEventType> {
+    /** Unique delivery id — also sent as the `X-Road-Delivery-Id` header. */
+    id: string;
+    /** The event type — also sent as the `X-Road-Event` header. */
+    event: T;
+    /** ISO-8601 timestamp of the delivery. */
+    timestamp: string;
+    /** Event-specific payload. */
+    data: RoadWebhookPayloads[T];
+}
+/**
+ * Runtime list of every webhook event type — handy for registering a
+ * subscription to "all events". `satisfies` guarantees no typo'd or
+ * stale entry slips in.
+ */
+declare const ROAD_WEBHOOK_EVENT_TYPES: readonly ["organization.invitation.created", "organization.invitation.accepted", "organization.invitation.rejected", "organization.invitation.cancelled", "organization.member.joined", "organization.member.suspended", "organization.member.reinstated", "organization.member.removed", "organization.member.role-changed"];
+
+export { type BUStatus, type BusinessUnitDetail, type BusinessUnitSummary, type CreateBusinessUnitInput, type CreateInvitationInput, type CreateRoleInput, type CurrentUser, type Invitation, type InvitationWebhookData, type Member, type MemberRoleChangedWebhookData, type MemberStatus, type MemberWebhookData, type Membership, type MyBusinessUnits, type MyPermissions, type PaginatedList, type Pagination, type PaginationInput, type PendingInvitation, type Permission, type PermissionTuple, ROAD_API_CONTRACT, ROAD_API_URLS, ROAD_WEBHOOK_EVENT_TYPES, type RoadApiContract, type RoadEnvironment, type RoadWebhookEvent, type RoadWebhookEventType, type RoadWebhookPayloads, type Role, type RoleRef, type ScopePermissions, type ScopePermissionsBulk, type UpdateBusinessUnitInput, type UpdateRoleInput };

package/dist/index.d.ts

@@ -33,7 +33,7 @@ declare const ROAD_API_URLS: {
 type RoadEnvironment = keyof typeof ROAD_API_URLS;
 
 type BUStatus = "active" | "suspended" | "archived";
-type MemberStatus = "active" | "suspended" | "pending";
+type MemberStatus = "active" | "suspended" | "removed";
 interface CurrentUser {
     id: string;
     name: string;
@@ -96,7 +96,7 @@ interface Invitation {
     email: string;
     roleId: string;
     roleName: string;
-    status: "pending" | "accepted" | "expired" | "cancelled";
+    status: "pending" | "accepted" | "expired" | "cancelled" | "rejected";
     invitedAt: string;
     expiresAt: string;
 }
@@ -106,7 +106,9 @@ interface Role {
     description: string;
     permissions: string[];
     isSystem: boolean;
-    memberCount: number;
+    /** Count of role assignments (users + service principals + groups). */
+    assignmentCount: number;
+    createdAt: string;
 }
 interface Permission {
     id: string;
@@ -115,19 +117,42 @@ interface Permission {
     description: string;
     /** Subject group (e.g. "Member", "Role", "BusinessUnit") used to group in the picker. */
     category: string;
+    scopeId: string;
+    createdAt: string;
 }
 /**
- * Effective permissions for the current user, keyed by business-unit ID.
- * A value of `["*"]` (ROAD_WILDCARD_PERMISSION) grants every action in that BU.
+ * Effective permissions for the current user, keyed by business-unit ID, as the
+ * **SDK** exposes them — each grant flattened to an `"action:subject"` string
+ * (`["*"]` grants every action in that BU). This is the client-side convenience
+ * shape; the raw wire form is `ScopePermissions` / `ScopePermissionsBulk` below,
+ * which the HTTP client maps into this.
  */
 type MyPermissions = Record<string, string[]>;
 /**
- * Cursor-paginated list response. The API issues opaque base64-url cursors
- * the client treats as opaque — no parsing or arithmetic on the SDK side.
+ * A single effective-permission grant exactly as the API returns it on the
+ * wire: an `action`/`subject` pair. Wildcards are returned as-is
+ * (`{ action: "*", subject: "*" }`), not enumerated.
+ */
+interface PermissionTuple {
+    action: string;
+    subject: string;
+}
+/** Wire shape of `GET /me/permissions?scope=<scopeId>` (single scope). */
+interface ScopePermissions {
+    permissions: PermissionTuple[];
+}
+/**
+ * Wire shape of `GET /me/permissions?scopes=<id>,<id>,…` — effective
+ * permissions keyed by scope id (the SDK's fan-in for multi-BU users).
+ */
+type ScopePermissionsBulk = Record<string, PermissionTuple[]>;
+/**
+ * Cursor-pagination metadata. The API issues opaque base64-url cursors the
+ * client treats as opaque — no parsing or arithmetic on the SDK side.
  * `cursor` is null when no further page exists; `hasMore` is the canonical
  * "more rows after this page" signal, redundant with `cursor !== null`.
  */
-interface PageInfo {
+interface Pagination {
     /** Opaque cursor for the next page. Null when this is the last page. */
     cursor: string | null;
     /** True iff there is at least one row past this page. */
@@ -136,13 +161,15 @@ interface PageInfo {
     totalCount: number;
 }
 /**
- * Generic paged response shape returned from listing endpoints with
- * cursor pagination (members, roles, invitations). Convertible 1:1 to
- * React Query's useInfiniteQuery `pageParam` flow via `pageInfo.cursor`.
+ * Canonical paged response shape for every list endpoint. Mirrors the API's
+ * universal `{ data }` envelope — the rows live under `data` (the same key
+ * as every single-resource response), with cursor `pagination` as a
+ * top-level sibling. Convertible 1:1 to React Query's useInfiniteQuery
+ * `pageParam` flow via `pagination.cursor`.
  */
 interface PaginatedList<T> {
-    items: T[];
-    pageInfo: PageInfo;
+    data: T[];
+    pagination: Pagination;
 }
 /**
  * Input shape for any paginated list call. Both fields are optional —
@@ -150,7 +177,7 @@ interface PaginatedList<T> {
  * (currently 20).
  */
 interface PaginationInput {
-    /** Opaque cursor from a previous `pageInfo.cursor`. Omit for the first page. */
+    /** Opaque cursor from a previous response's `pagination.cursor`. Omit for the first page. */
     cursor?: string;
     /** Page size. Default 20, max 100 (server-enforced). */
     limit?: number;
@@ -163,19 +190,19 @@ interface CreateBusinessUnitInput {
 }
 interface UpdateBusinessUnitInput {
     name?: string;
-    slug?: string;
+    joinCode?: string | null;
     memberLimit?: number | null;
 }
 interface CreateRoleInput {
     name: string;
-    description?: string;
+    description?: string | null;
     permissions: string[];
     /** Source role ID when "clone from existing"; informational only. */
     cloneFromRoleId?: string;
 }
 interface UpdateRoleInput {
     name?: string;
-    description?: string;
+    description?: string | null;
     permissions?: string[];
 }
 interface CreateInvitationInput {
@@ -183,4 +210,67 @@ interface CreateInvitationInput {
     roleId: string;
 }
 
-export { type BUStatus, type BusinessUnitDetail, type BusinessUnitSummary, type CreateBusinessUnitInput, type CreateInvitationInput, type CreateRoleInput, type CurrentUser, type Invitation, type Member, type MemberStatus, type Membership, type MyBusinessUnits, type MyPermissions, type PageInfo, type PaginatedList, type PaginationInput, type PendingInvitation, type Permission, ROAD_API_CONTRACT, ROAD_API_URLS, type RoadApiContract, type RoadEnvironment, type Role, type RoleRef, type UpdateBusinessUnitInput, type UpdateRoleInput };
+/**
+ * Road webhook events — the canonical wire contract every SDK builds on.
+ *
+ * The event-type strings and `data` payloads mirror exactly what the Road API
+ * delivers: the `event` and `data` fields of the webhook POST body, and the
+ * `X-Road-Event` header. SDKs that receive webhooks import from here and never
+ * redefine them (SDK DX Bar principle 11 — one source of truth).
+ *
+ * Only the public `organization.*` events are listed; internal/experimental
+ * event namespaces are intentionally excluded from the SDK surface.
+ */
+/** Payload for every `organization.invitation.*` event. */
+interface InvitationWebhookData {
+    businessUnitId: string;
+    invitationId: string;
+    email: string;
+}
+/** Payload for `organization.member.{joined,suspended,reinstated,removed}`. */
+interface MemberWebhookData {
+    businessUnitId: string;
+    memberId: string;
+    userId: string;
+}
+/** Payload for `organization.member.role-changed`. */
+interface MemberRoleChangedWebhookData extends MemberWebhookData {
+    roleId: string;
+    action: "assigned" | "revoked";
+}
+/** Maps each webhook event type to the shape of its `data` payload. */
+interface RoadWebhookPayloads {
+    "organization.invitation.created": InvitationWebhookData;
+    "organization.invitation.accepted": InvitationWebhookData;
+    "organization.invitation.rejected": InvitationWebhookData;
+    "organization.invitation.cancelled": InvitationWebhookData;
+    "organization.member.joined": MemberWebhookData;
+    "organization.member.suspended": MemberWebhookData;
+    "organization.member.reinstated": MemberWebhookData;
+    "organization.member.removed": MemberWebhookData;
+    "organization.member.role-changed": MemberRoleChangedWebhookData;
+}
+/** Every webhook event type the Road API can deliver. */
+type RoadWebhookEventType = keyof RoadWebhookPayloads;
+/**
+ * The exact envelope the Road API POSTs to a registered webhook URL —
+ * mirrors the delivered body `{ id, event, timestamp, data }`.
+ */
+interface RoadWebhookEvent<T extends RoadWebhookEventType = RoadWebhookEventType> {
+    /** Unique delivery id — also sent as the `X-Road-Delivery-Id` header. */
+    id: string;
+    /** The event type — also sent as the `X-Road-Event` header. */
+    event: T;
+    /** ISO-8601 timestamp of the delivery. */
+    timestamp: string;
+    /** Event-specific payload. */
+    data: RoadWebhookPayloads[T];
+}
+/**
+ * Runtime list of every webhook event type — handy for registering a
+ * subscription to "all events". `satisfies` guarantees no typo'd or
+ * stale entry slips in.
+ */
+declare const ROAD_WEBHOOK_EVENT_TYPES: readonly ["organization.invitation.created", "organization.invitation.accepted", "organization.invitation.rejected", "organization.invitation.cancelled", "organization.member.joined", "organization.member.suspended", "organization.member.reinstated", "organization.member.removed", "organization.member.role-changed"];
+
+export { type BUStatus, type BusinessUnitDetail, type BusinessUnitSummary, type CreateBusinessUnitInput, type CreateInvitationInput, type CreateRoleInput, type CurrentUser, type Invitation, type InvitationWebhookData, type Member, type MemberRoleChangedWebhookData, type MemberStatus, type MemberWebhookData, type Membership, type MyBusinessUnits, type MyPermissions, type PaginatedList, type Pagination, type PaginationInput, type PendingInvitation, type Permission, type PermissionTuple, ROAD_API_CONTRACT, ROAD_API_URLS, ROAD_WEBHOOK_EVENT_TYPES, type RoadApiContract, type RoadEnvironment, type RoadWebhookEvent, type RoadWebhookEventType, type RoadWebhookPayloads, type Role, type RoleRef, type ScopePermissions, type ScopePermissionsBulk, type UpdateBusinessUnitInput, type UpdateRoleInput };

package/dist/index.js

@@ -25,11 +25,25 @@ var ROAD_CORE_SUBJECTS = [
   "Invitation"
 ];
 var ROAD_WILDCARD_PERMISSION = "*";
+
+// src/webhooks.ts
+var ROAD_WEBHOOK_EVENT_TYPES = [
+  "organization.invitation.created",
+  "organization.invitation.accepted",
+  "organization.invitation.rejected",
+  "organization.invitation.cancelled",
+  "organization.member.joined",
+  "organization.member.suspended",
+  "organization.member.reinstated",
+  "organization.member.removed",
+  "organization.member.role-changed"
+];
 export {
   ROAD_API_CONTRACT,
   ROAD_API_URLS,
   ROAD_CORE_ACTIONS,
   ROAD_CORE_SUBJECTS,
+  ROAD_WEBHOOK_EVENT_TYPES,
   ROAD_WILDCARD_PERMISSION
 };
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/api-contract.ts","../src/api-urls.ts","../src/permissions.ts"],"sourcesContent":["/**\n * The Road API **contract version** — the major boundary of the HTTP wire\n * surface. The Road API mounts every route under `/api/<contract>`, and every\n * SDK builds its base path as `${host}/api/${ROAD_API_CONTRACT}`.\n *\n * This is the single source of truth for that value. The Road API imports it\n * for its global prefix; the in-repo clients (admin, tester) and the published\n * SDKs read it from here. It is **not** environment configuration — it is\n * identical in every environment and changes only by a deliberate edit when the\n * wire contract makes a breaking change: `alpha` → `v1` → `v2`.\n *\n * Promoting this from `alpha` to `v1` is the trigger to take the SDKs to their\n * first stable `1.0.0`. See `docs/plans/14-sdk-publishing-and-versioning.md`.\n */\nexport const ROAD_API_CONTRACT = \"alpha\" as const;\n\nexport type RoadApiContract = typeof ROAD_API_CONTRACT;\n","/**\n * Road's hosted API base URLs. SDKs default to ROAD_API_URLS.production; the\n * sandbox URL is the deployed Road sandbox (override via the SDK's apiBaseUrl\n * config if you're running against a different environment, eg. local dev or\n * a private staging cluster).\n *\n * If the deployed sandbox hostname changes, update this constant — it's the\n * single source of truth every SDK reads from.\n */\nexport const ROAD_API_URLS = {\n  production: \"https://api.road.app\",\n  sandbox: \"https://api.road-sandbox.b1.app\",\n} as const;\n\nexport type RoadEnvironment = keyof typeof ROAD_API_URLS;\n","/**\n * Road IAM permission algebra. Permissions are `${action}:${subject}` strings;\n * the wildcard `\"*\"` short-circuits to true for every action in a scope.\n *\n * The widget catalog calls into actions and subjects Road ships by default\n * (the union types below). Platforms can declare their own actions and\n * subjects in their IAM catalog — those flow through useCan as plain strings,\n * still type-safe via `RoadPermission | (string & {})` in the React SDK.\n */\n\n/**\n * The CRUD verbs Road's IAM engine recognizes, plus `manage` which the\n * engine expands server-side into the full CRUD set for the same subject\n * (`manage:Member` ⇒ also `create|read|update|delete:Member` in the\n * effective-permissions response).\n *\n * Platforms can register their own actions (`approve`, `submit`, `list`, …)\n * — those flow through useCan as plain strings (the `(string & {})` part\n * of PermissionInput in the React SDK), still type-safe via that escape.\n */\nexport type RoadAction = \"create\" | \"read\" | \"update\" | \"delete\" | \"manage\";\n\n/**\n * Built-in subjects Road's own permissions cover. Mirrors the subjects\n * registered in the API's `Subjects` constant\n * (apps/api/src/modules/iam/authorization/constants/subjects.ts), limited\n * to the subjects user-facing widgets actually surface:\n *\n *   - BusinessUnit: system-level — create new BUs\n *   - BUDashboard: BU-level — read a BU's detail page\n *   - BUSettings: BU-level — edit a BU's settings\n *   - Member, Role, Permission, Invitation: BU-level CRUD\n *\n * Admin / platform-engineer subjects (System, Platform, AdminUser,\n * PlatformIdentity, …) are not exposed here — they belong to a future\n * developer-facing widget (and admin SDK), not the customer-facing toolkit.\n *\n * Platform-specific subjects (eg. A4L's `Agent`) are not enumerated —\n * platforms register them at runtime under their own scope, and useCan's\n * `(string & {})` accepts them without complaint.\n */\nexport type RoadCoreSubject =\n  | \"BusinessUnit\"\n  | \"BUDashboard\"\n  | \"BUSettings\"\n  | \"Member\"\n  | \"Role\"\n  | \"Permission\"\n  | \"Invitation\";\n\n/** `${action}:${Subject}` for the core set, plus the wildcard. */\nexport type RoadPermission = `${RoadAction}:${RoadCoreSubject}` | \"*\";\n\n/** Runtime array of the core actions — handy for iteration or validation. */\nexport const ROAD_CORE_ACTIONS = [\n  \"create\",\n  \"read\",\n  \"update\",\n  \"delete\",\n  \"manage\",\n] as const satisfies readonly RoadAction[];\n\n/** Runtime array of the core subjects — handy for iteration or validation. */\nexport const ROAD_CORE_SUBJECTS = [\n  \"BusinessUnit\",\n  \"BUDashboard\",\n  \"BUSettings\",\n  \"Member\",\n  \"Role\",\n  \"Permission\",\n  \"Invitation\",\n] as const satisfies readonly RoadCoreSubject[];\n\n/** The wildcard permission string. Use this instead of literal \"*\" for grep-ability. */\nexport const ROAD_WILDCARD_PERMISSION = \"*\" as const;\n"],"mappings":";AAcO,IAAM,oBAAoB;;;ACL1B,IAAM,gBAAgB;AAAA,EAC3B,YAAY;AAAA,EACZ,SAAS;AACX;;;AC0CO,IAAM,oBAAoB;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,qBAAqB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,2BAA2B;","names":[]}
+{"version":3,"sources":["../src/api-contract.ts","../src/api-urls.ts","../src/permissions.ts","../src/webhooks.ts"],"sourcesContent":["/**\n * The Road API **contract version** — the major boundary of the HTTP wire\n * surface. The Road API mounts every route under `/api/<contract>`, and every\n * SDK builds its base path as `${host}/api/${ROAD_API_CONTRACT}`.\n *\n * This is the single source of truth for that value. The Road API imports it\n * for its global prefix; the in-repo clients (admin, tester) and the published\n * SDKs read it from here. It is **not** environment configuration — it is\n * identical in every environment and changes only by a deliberate edit when the\n * wire contract makes a breaking change: `alpha` → `v1` → `v2`.\n *\n * Promoting this from `alpha` to `v1` is the trigger to take the SDKs to their\n * first stable `1.0.0`. See `docs/plans/14-sdk-publishing-and-versioning.md`.\n */\nexport const ROAD_API_CONTRACT = \"alpha\" as const;\n\nexport type RoadApiContract = typeof ROAD_API_CONTRACT;\n","/**\n * Road's hosted API base URLs. SDKs default to ROAD_API_URLS.production; the\n * sandbox URL is the deployed Road sandbox (override via the SDK's apiBaseUrl\n * config if you're running against a different environment, eg. local dev or\n * a private staging cluster).\n *\n * If the deployed sandbox hostname changes, update this constant — it's the\n * single source of truth every SDK reads from.\n */\nexport const ROAD_API_URLS = {\n  production: \"https://api.road.app\",\n  sandbox: \"https://api.road-sandbox.b1.app\",\n} as const;\n\nexport type RoadEnvironment = keyof typeof ROAD_API_URLS;\n","/**\n * Road IAM permission algebra. Permissions are `${action}:${subject}` strings;\n * the wildcard `\"*\"` short-circuits to true for every action in a scope.\n *\n * The widget catalog calls into actions and subjects Road ships by default\n * (the union types below). Platforms can declare their own actions and\n * subjects in their IAM catalog — those flow through useCan as plain strings,\n * still type-safe via `RoadPermission | (string & {})` in the React SDK.\n */\n\n/**\n * The CRUD verbs Road's IAM engine recognizes, plus `manage` which the\n * engine expands server-side into the full CRUD set for the same subject\n * (`manage:Member` ⇒ also `create|read|update|delete:Member` in the\n * effective-permissions response).\n *\n * Platforms can register their own actions (`approve`, `submit`, `list`, …)\n * — those flow through useCan as plain strings (the `(string & {})` part\n * of PermissionInput in the React SDK), still type-safe via that escape.\n */\nexport type RoadAction = \"create\" | \"read\" | \"update\" | \"delete\" | \"manage\";\n\n/**\n * Built-in subjects Road's own permissions cover. Mirrors the subjects\n * registered in the API's `Subjects` constant\n * (apps/api/src/modules/iam/authorization/constants/subjects.ts), limited\n * to the subjects user-facing widgets actually surface:\n *\n *   - BusinessUnit: system-level — create new BUs\n *   - BUDashboard: BU-level — read a BU's detail page\n *   - BUSettings: BU-level — edit a BU's settings\n *   - Member, Role, Permission, Invitation: BU-level CRUD\n *\n * Admin / platform-engineer subjects (System, Platform, AdminUser,\n * PlatformIdentity, …) are not exposed here — they belong to a future\n * developer-facing widget (and admin SDK), not the customer-facing toolkit.\n *\n * Platform-specific subjects (eg. A4L's `Agent`) are not enumerated —\n * platforms register them at runtime under their own scope, and useCan's\n * `(string & {})` accepts them without complaint.\n */\nexport type RoadCoreSubject =\n  | \"BusinessUnit\"\n  | \"BUDashboard\"\n  | \"BUSettings\"\n  | \"Member\"\n  | \"Role\"\n  | \"Permission\"\n  | \"Invitation\";\n\n/** `${action}:${Subject}` for the core set, plus the wildcard. */\nexport type RoadPermission = `${RoadAction}:${RoadCoreSubject}` | \"*\";\n\n/** Runtime array of the core actions — handy for iteration or validation. */\nexport const ROAD_CORE_ACTIONS = [\n  \"create\",\n  \"read\",\n  \"update\",\n  \"delete\",\n  \"manage\",\n] as const satisfies readonly RoadAction[];\n\n/** Runtime array of the core subjects — handy for iteration or validation. */\nexport const ROAD_CORE_SUBJECTS = [\n  \"BusinessUnit\",\n  \"BUDashboard\",\n  \"BUSettings\",\n  \"Member\",\n  \"Role\",\n  \"Permission\",\n  \"Invitation\",\n] as const satisfies readonly RoadCoreSubject[];\n\n/** The wildcard permission string. Use this instead of literal \"*\" for grep-ability. */\nexport const ROAD_WILDCARD_PERMISSION = \"*\" as const;\n","/**\n * Road webhook events — the canonical wire contract every SDK builds on.\n *\n * The event-type strings and `data` payloads mirror exactly what the Road API\n * delivers: the `event` and `data` fields of the webhook POST body, and the\n * `X-Road-Event` header. SDKs that receive webhooks import from here and never\n * redefine them (SDK DX Bar principle 11 — one source of truth).\n *\n * Only the public `organization.*` events are listed; internal/experimental\n * event namespaces are intentionally excluded from the SDK surface.\n */\n\n/** Payload for every `organization.invitation.*` event. */\nexport interface InvitationWebhookData {\n  businessUnitId: string;\n  invitationId: string;\n  email: string;\n}\n\n/** Payload for `organization.member.{joined,suspended,reinstated,removed}`. */\nexport interface MemberWebhookData {\n  businessUnitId: string;\n  memberId: string;\n  userId: string;\n}\n\n/** Payload for `organization.member.role-changed`. */\nexport interface MemberRoleChangedWebhookData extends MemberWebhookData {\n  roleId: string;\n  action: \"assigned\" | \"revoked\";\n}\n\n/** Maps each webhook event type to the shape of its `data` payload. */\nexport interface RoadWebhookPayloads {\n  \"organization.invitation.created\": InvitationWebhookData;\n  \"organization.invitation.accepted\": InvitationWebhookData;\n  \"organization.invitation.rejected\": InvitationWebhookData;\n  \"organization.invitation.cancelled\": InvitationWebhookData;\n  \"organization.member.joined\": MemberWebhookData;\n  \"organization.member.suspended\": MemberWebhookData;\n  \"organization.member.reinstated\": MemberWebhookData;\n  \"organization.member.removed\": MemberWebhookData;\n  \"organization.member.role-changed\": MemberRoleChangedWebhookData;\n}\n\n/** Every webhook event type the Road API can deliver. */\nexport type RoadWebhookEventType = keyof RoadWebhookPayloads;\n\n/**\n * The exact envelope the Road API POSTs to a registered webhook URL —\n * mirrors the delivered body `{ id, event, timestamp, data }`.\n */\nexport interface RoadWebhookEvent<\n  T extends RoadWebhookEventType = RoadWebhookEventType,\n> {\n  /** Unique delivery id — also sent as the `X-Road-Delivery-Id` header. */\n  id: string;\n  /** The event type — also sent as the `X-Road-Event` header. */\n  event: T;\n  /** ISO-8601 timestamp of the delivery. */\n  timestamp: string;\n  /** Event-specific payload. */\n  data: RoadWebhookPayloads[T];\n}\n\n/**\n * Runtime list of every webhook event type — handy for registering a\n * subscription to \"all events\". `satisfies` guarantees no typo'd or\n * stale entry slips in.\n */\nexport const ROAD_WEBHOOK_EVENT_TYPES = [\n  \"organization.invitation.created\",\n  \"organization.invitation.accepted\",\n  \"organization.invitation.rejected\",\n  \"organization.invitation.cancelled\",\n  \"organization.member.joined\",\n  \"organization.member.suspended\",\n  \"organization.member.reinstated\",\n  \"organization.member.removed\",\n  \"organization.member.role-changed\",\n] as const satisfies readonly RoadWebhookEventType[];\n"],"mappings":";AAcO,IAAM,oBAAoB;;;ACL1B,IAAM,gBAAgB;AAAA,EAC3B,YAAY;AAAA,EACZ,SAAS;AACX;;;AC0CO,IAAM,oBAAoB;AAAA,EAC/B;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,qBAAqB;AAAA,EAChC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;AAGO,IAAM,2BAA2B;;;ACJjC,IAAM,2BAA2B;AAAA,EACtC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,EACA;AACF;","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b1-road/types",
-  "version": "0.1.0-alpha.0",
+  "version": "0.1.0-alpha.1",
   "type": "module",
   "description": "Shared types and constants for every @b1-road SDK — entities, permission algebra, hosted API URLs.",
   "license": "MIT",
@@ -27,12 +27,24 @@
   "types": "./dist/index.d.ts",
   "exports": {
     ".": {
-      "import": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
-      "require": { "types": "./dist/index.d.cts", "default": "./dist/index.cjs" }
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
     },
     "./iam": {
-      "import": { "types": "./dist/iam.d.ts", "default": "./dist/iam.js" },
-      "require": { "types": "./dist/iam.d.cts", "default": "./dist/iam.cjs" }
+      "import": {
+        "types": "./dist/iam.d.ts",
+        "default": "./dist/iam.js"
+      },
+      "require": {
+        "types": "./dist/iam.d.cts",
+        "default": "./dist/iam.cjs"
+      }
     }
   },
   "files": [