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

package/README.md

@@ -13,7 +13,7 @@ redefine.
 ## Install
 
 ```sh
-npm install @b1-road/types@alpha
+npm install @b1-road/types
 ```
 
 Ships dual ESM/CJS builds with type declarations. Zero runtime dependencies.

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}\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/**\n * Subjects the IAM engine can authorize. `service` covers M2M. (`api_key` was a\n * legacy subject the API never accepted — `SUBJECT_TYPES` is `['user','service']`\n * — so it is intentionally absent: the contract must not advertise a value the\n * API rejects.)\n */\nexport type SubjectType = \"user\" | \"service\";\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   * Hydrated convenience field the **list** endpoint\n   * (`GET /subjects/:type/:id/assignments`) includes so a client can show the\n   * role name without a follow-up lookup. Omitted by endpoints that return a\n   * bare assignment (e.g. `assignments.create`), hence optional.\n   */\n  roleName?: string;\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  /**\n   * The IAM subject to authorize — a **Road user id** (the profile UUID), a\n   * service id, or an api-key id.\n   *\n   * Optional: **when omitted, the API authorizes the authenticated caller**\n   * derived from the access token. Cookie-mode SDKs (`@b1-road/nestjs`) rely on\n   * this — they carry the caller's token, not their Road user id, so they omit\n   * `subjectId` rather than passing the Auth Server `sub` (which IAM does not\n   * key subjects by). Server-to-server callers that authorize *another* subject\n   * pass its Road user/service id explicitly.\n   */\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  /** Optional — same semantics as {@link AuthorizeInput.subjectId} (omitted = the authenticated caller). */\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

@@ -12,8 +12,13 @@ import { e as RoadPermission } from './permissions-BSbomCrB.cjs';
 
 /** Scope shape. Three flavors today; platforms may register more over time. */
 type ScopeType = "system" | "business_unit" | "platform";
-/** Subjects the IAM engine can authorize. `service` covers M2M; `api_key` is legacy. */
-type SubjectType = "user" | "service" | "api_key";
+/**
+ * Subjects the IAM engine can authorize. `service` covers M2M. (`api_key` was a
+ * legacy subject the API never accepted — `SUBJECT_TYPES` is `['user','service']`
+ * — so it is intentionally absent: the contract must not advertise a value the
+ * API rejects.)
+ */
+type SubjectType = "user" | "service";
 interface Scope {
     id: string;
     type: ScopeType;
@@ -43,6 +48,13 @@ interface Assignment {
     grantedBy: string;
     grantedAt: string;
     expiresAt: string | null;
+    /**
+     * Hydrated convenience field the **list** endpoint
+     * (`GET /subjects/:type/:id/assignments`) includes so a client can show the
+     * role name without a follow-up lookup. Omitted by endpoints that return a
+     * bare assignment (e.g. `assignments.create`), hence optional.
+     */
+    roleName?: string;
 }
 interface CreateAssignmentInput {
     subjectType: SubjectType;
@@ -53,7 +65,18 @@ interface CreateAssignmentInput {
 }
 interface AuthorizeInput {
     subjectType: SubjectType;
-    subjectId: string;
+    /**
+     * The IAM subject to authorize — a **Road user id** (the profile UUID), a
+     * service id, or an api-key id.
+     *
+     * Optional: **when omitted, the API authorizes the authenticated caller**
+     * derived from the access token. Cookie-mode SDKs (`@b1-road/nestjs`) rely on
+     * this — they carry the caller's token, not their Road user id, so they omit
+     * `subjectId` rather than passing the Auth Server `sub` (which IAM does not
+     * key subjects by). Server-to-server callers that authorize *another* subject
+     * pass its Road user/service id explicitly.
+     */
+    subjectId?: string;
     scopeId: string;
     /** Either a single permission string (`"read:Member"`) or the wildcard. */
     permission: RoadPermission | (string & {});
@@ -64,7 +87,8 @@ interface AuthorizeResult {
 }
 interface AuthorizeBatchInput {
     subjectType: SubjectType;
-    subjectId: string;
+    /** Optional — same semantics as {@link AuthorizeInput.subjectId} (omitted = the authenticated caller). */
+    subjectId?: string;
     scopeId: string;
     permissions: Array<RoadPermission | (string & {})>;
 }

package/dist/iam.d.ts

@@ -12,8 +12,13 @@ import { e as RoadPermission } from './permissions-BSbomCrB.js';
 
 /** Scope shape. Three flavors today; platforms may register more over time. */
 type ScopeType = "system" | "business_unit" | "platform";
-/** Subjects the IAM engine can authorize. `service` covers M2M; `api_key` is legacy. */
-type SubjectType = "user" | "service" | "api_key";
+/**
+ * Subjects the IAM engine can authorize. `service` covers M2M. (`api_key` was a
+ * legacy subject the API never accepted — `SUBJECT_TYPES` is `['user','service']`
+ * — so it is intentionally absent: the contract must not advertise a value the
+ * API rejects.)
+ */
+type SubjectType = "user" | "service";
 interface Scope {
     id: string;
     type: ScopeType;
@@ -43,6 +48,13 @@ interface Assignment {
     grantedBy: string;
     grantedAt: string;
     expiresAt: string | null;
+    /**
+     * Hydrated convenience field the **list** endpoint
+     * (`GET /subjects/:type/:id/assignments`) includes so a client can show the
+     * role name without a follow-up lookup. Omitted by endpoints that return a
+     * bare assignment (e.g. `assignments.create`), hence optional.
+     */
+    roleName?: string;
 }
 interface CreateAssignmentInput {
     subjectType: SubjectType;
@@ -53,7 +65,18 @@ interface CreateAssignmentInput {
 }
 interface AuthorizeInput {
     subjectType: SubjectType;
-    subjectId: string;
+    /**
+     * The IAM subject to authorize — a **Road user id** (the profile UUID), a
+     * service id, or an api-key id.
+     *
+     * Optional: **when omitted, the API authorizes the authenticated caller**
+     * derived from the access token. Cookie-mode SDKs (`@b1-road/nestjs`) rely on
+     * this — they carry the caller's token, not their Road user id, so they omit
+     * `subjectId` rather than passing the Auth Server `sub` (which IAM does not
+     * key subjects by). Server-to-server callers that authorize *another* subject
+     * pass its Road user/service id explicitly.
+     */
+    subjectId?: string;
     scopeId: string;
     /** Either a single permission string (`"read:Member"`) or the wildcard. */
     permission: RoadPermission | (string & {});
@@ -64,7 +87,8 @@ interface AuthorizeResult {
 }
 interface AuthorizeBatchInput {
     subjectType: SubjectType;
-    subjectId: string;
+    /** Optional — same semantics as {@link AuthorizeInput.subjectId} (omitted = the authenticated caller). */
+    subjectId?: string;
     scopeId: string;
     permissions: Array<RoadPermission | (string & {})>;
 }

package/dist/index.d.cts

@@ -97,6 +97,13 @@ interface Invitation {
     roleId: string;
     roleName: string;
     status: "pending" | "accepted" | "expired" | "cancelled" | "rejected";
+    /**
+     * How the invitation was accepted: `"manual"` (the user explicitly accepted)
+     * or `"auto"` (auto-linked when the invited user first signed in with a
+     * pending invitation). `null` while still pending — and for invitations
+     * accepted before this field existed.
+     */
+    acceptedVia: "manual" | "auto" | null;
     invitedAt: string;
     expiresAt: string;
 }

package/dist/index.d.ts

@@ -97,6 +97,13 @@ interface Invitation {
     roleId: string;
     roleName: string;
     status: "pending" | "accepted" | "expired" | "cancelled" | "rejected";
+    /**
+     * How the invitation was accepted: `"manual"` (the user explicitly accepted)
+     * or `"auto"` (auto-linked when the invited user first signed in with a
+     * pending invitation). `null` while still pending — and for invitations
+     * accepted before this field existed.
+     */
+    acceptedVia: "manual" | "auto" | null;
     invitedAt: string;
     expiresAt: string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@b1-road/types",
-  "version": "0.1.0-alpha.1",
+  "version": "0.1.0-alpha.3",
   "type": "module",
   "description": "Shared types and constants for every @b1-road SDK — entities, permission algebra, hosted API URLs.",
   "license": "MIT",