@guinetik/primitives-ts 0.8.2 → 0.8.3

package/README.md

@@ -151,62 +151,52 @@ Available type guards:
 
 ### Publishing Process
 
-When you make changes to primitives:
+Releases are published to the public npm registry by **GitHub Actions using npm
+trusted publishing (OIDC)** — there is no npm token to fetch or set, and
+`npm publish` is never run by hand.
 
-1. **Bump the version** (automatically updates package.json and creates git tag):
+1. **Make and test your changes** in `src/`, then check the consumers compile:
    ```bash
-   cd primitives
-   npm version patch  # for bug fixes (0.2.5 -> 0.2.6)
-   npm version minor  # for new features (0.2.5 -> 0.3.0)
-   npm version major  # for breaking changes (0.2.5 -> 1.0.0)
+   npm test && npm run build
+   # temporary overlay for a quick type-check; the real install replaces it later
+   cp -r dist/* ../api/node_modules/@guinetik/primitives-ts/dist/ && (cd ../api && npx tsc --noEmit)
    ```
 
-2. **Build the package**:
-   ```bash
-   npm run build
+2. **Cut the release** from the monorepo root (bumps `package.json`, commits,
+   tags `primitives-v<version>`, pushes branch + tag):
+   ```powershell
+   .\scripts\release-primitives.ps1             # patch: 0.8.1 -> 0.8.2
+   .\scripts\release-primitives.ps1 -Bump minor # 0.8.1 -> 0.9.0
    ```
 
-3. **Publish to npm** (requires `NPM_KEY` environment variable):
+3. **Wait for the workflow** (`.github/workflows/publish-primitives.yml`,
+   about a minute) and confirm the registry has it:
    ```bash
-   # The NPM_KEY is stored in Bitwarden and should be set as environment variable
-   # Set it with: $env:NPM_KEY = "your-npm-access-token"
-   npm publish --access public
+   npm view @guinetik/primitives-ts version
    ```
 
-4. **Update dependent projects** (api, admin):
+4. **Pin the new version in dependent projects** (exact, no `^`/`~`):
    ```bash
-   # In api/package.json or admin/package.json, update the version:
-   # "@guinetik/primitives-ts": "0.2.6"  (use exact version, no ^ or ~)
-   
-   # Then install in each project
-   cd ../api
-   npm install
-   
-   cd ../admin
-   npm install
+   cd ../api   && npm install --save-exact @guinetik/primitives-ts@<version>
+   cd ../admin && npm install --save-exact @guinetik/primitives-ts@<version>
+   cd ../db    && npm install --save-exact @guinetik/primitives-ts@<version>
    ```
 
+Full details, one-time trusted-publisher setup and troubleshooting:
+[`docs/development/primitives-publishing.md`](../docs/development/primitives-publishing.md).
+
 ### Why No Local Linking?
 
 - **Prevents version drift** - Ensures all projects use exact versions
 - **Avoids build issues** - npm link can cause TypeScript declaration file problems
-- **Deployment consistency** - Production uses npm packages, dev should match
-- **Simple workflow** - Publish is fast and ensures types are properly compiled
-
-### NPM Authentication
+- **Deployment consistency** - Docker build contexts are the app folders, so `../primitives` does not exist there
+- **Simple workflow** - A tag push publishes; consumers just `npm install`
 
-The `NPM_KEY` environment variable contains the npm access token for publishing:
-- Stored in: Bitwarden Secrets Manager
-- Secret name: `NPM_KEY`
-- Used by: Local development, CI/CD, and autonomous agents
+### Authentication
 
-```bash
-# Fetch from Bitwarden (if you have access)
-$env:NPM_KEY = (bws secret get NPM_KEY --output json | ConvertFrom-Json).value
-
-# Or set manually if you have the token
-$env:NPM_KEY = "npm_xxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
-```
+None. Installing the package needs no credentials (it is public), and
+publishing is authenticated by the GitHub Actions workflow's OIDC identity,
+registered on npmjs.com as the package's trusted publisher.
 
 ## License
 

package/dist/access.types.d.ts

@@ -0,0 +1,98 @@
+/**
+ * Feature-based access control types shared between API and Admin.
+ */
+import type { User } from './auth.types';
+/** Application roles for admin panel users. */
+export type AdminRole = 'admin' | 'guest';
+/** Lifecycle status for admin directory records. */
+export type AdminUserStatus = 'invited' | 'active' | 'disabled';
+/** Avatar resolution strategy for admin users. */
+export type AvatarSource = 'gravatar' | 'google' | 'custom';
+/** Feature keys that gate admin panel pages and API areas. */
+export type FeatureKey = 'dashboard' | 'site' | 'runtime' | 'files' | 'launchpad' | 'users' | 'system' | 'chat' | 'agents';
+/** Canonical ordered list of grantable features. */
+export declare const FEATURE_CATALOG: readonly FeatureKey[];
+/** Human-readable labels for feature checklist UI. */
+export declare const FEATURE_LABELS: Record<FeatureKey, string>;
+/**
+ * Returns true when the value is a known feature key.
+ *
+ * @param value - Candidate feature key.
+ */
+export declare function isFeatureKey(value: unknown): value is FeatureKey;
+/**
+ * Normalizes and validates a feature grant list.
+ *
+ * @param features - Raw feature keys from input or Firestore.
+ * @returns Deduplicated feature keys in catalog order.
+ * @throws Error when an unknown or duplicate value is present.
+ */
+export declare function normalizeFeatureKeys(features: unknown): FeatureKey[];
+/** Authenticated admin panel user returned by `/auth/me` and login flows. */
+export interface AuthenticatedUser extends User {
+    role?: AdminRole;
+    features?: FeatureKey[];
+    status?: AdminUserStatus;
+    avatarSource?: AvatarSource;
+}
+/** Admin directory user exposed by `/users` management APIs. */
+export interface AdminUser {
+    id: string;
+    uid?: string;
+    email: string;
+    displayName?: string;
+    role: AdminRole;
+    features: FeatureKey[];
+    status: AdminUserStatus;
+    avatarSource: AvatarSource;
+    photoURL: string;
+    customPhotoURL?: string;
+    emailVerified: boolean;
+    invitedByUid?: string;
+    createdAt: string;
+    updatedAt: string;
+    lastSignInAt?: string;
+}
+/** Payload for inviting a new admin panel user. */
+export interface InviteAdminUserInput {
+    email: string;
+    displayName?: string;
+    role?: AdminRole;
+    features?: FeatureKey[];
+}
+/** Payload for updating an admin directory user. */
+export interface UpdateAdminUserInput {
+    displayName?: string;
+    status?: AdminUserStatus;
+    avatarSource?: AvatarSource;
+    customPhotoURL?: string;
+    role?: AdminRole;
+    features?: FeatureKey[];
+}
+/**
+ * Resolves the effective role for legacy documents without an explicit role.
+ *
+ * @param role - Stored role, if any.
+ */
+export declare function resolveAdminRole(role?: AdminRole): AdminRole;
+/**
+ * Returns whether the user has admin-level unrestricted access.
+ *
+ * @param user - Authenticated or directory user.
+ */
+export declare function isAdminUser(user: Pick<AuthenticatedUser, 'role'>): boolean;
+/**
+ * Checks whether a user may access a feature.
+ *
+ * @param user - Authenticated user with role and feature grants.
+ * @param feature - Required feature key.
+ */
+export declare function userHasFeature(user: Pick<AuthenticatedUser, 'role' | 'features'>, feature: FeatureKey): boolean;
+/**
+ * Checks whether a user may access at least one of the given features.
+ *
+ * @param user - Authenticated user with role and feature grants.
+ * @param features - Candidate feature keys.
+ */
+export declare function userHasAnyFeature(user: Pick<AuthenticatedUser, 'role' | 'features'>, features: readonly FeatureKey[]): boolean;
+//# sourceMappingURL=access.types.d.ts.map

package/dist/access.types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.types.d.ts","sourceRoot":"","sources":["../src/access.types.ts"],"names":[],"mappings":"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"}

package/dist/access.types.js

@@ -0,0 +1,105 @@
+"use strict";
+/**
+ * Feature-based access control types shared between API and Admin.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FEATURE_LABELS = exports.FEATURE_CATALOG = void 0;
+exports.isFeatureKey = isFeatureKey;
+exports.normalizeFeatureKeys = normalizeFeatureKeys;
+exports.resolveAdminRole = resolveAdminRole;
+exports.isAdminUser = isAdminUser;
+exports.userHasFeature = userHasFeature;
+exports.userHasAnyFeature = userHasAnyFeature;
+/** Canonical ordered list of grantable features. */
+exports.FEATURE_CATALOG = [
+    'dashboard',
+    'site',
+    'runtime',
+    'files',
+    'launchpad',
+    'users',
+    'system',
+    'chat',
+    'agents',
+];
+/** Human-readable labels for feature checklist UI. */
+exports.FEATURE_LABELS = {
+    dashboard: 'Dashboard',
+    site: 'Site',
+    runtime: 'Runtime',
+    files: 'File uploads',
+    launchpad: 'Launchpad',
+    users: 'Users',
+    system: 'System monitoring',
+    chat: 'Chat',
+    agents: 'Agents',
+};
+/**
+ * Returns true when the value is a known feature key.
+ *
+ * @param value - Candidate feature key.
+ */
+function isFeatureKey(value) {
+    return typeof value === 'string' && exports.FEATURE_CATALOG.includes(value);
+}
+/**
+ * Normalizes and validates a feature grant list.
+ *
+ * @param features - Raw feature keys from input or Firestore.
+ * @returns Deduplicated feature keys in catalog order.
+ * @throws Error when an unknown or duplicate value is present.
+ */
+function normalizeFeatureKeys(features) {
+    if (!Array.isArray(features)) {
+        throw new Error('Features must be an array');
+    }
+    const seen = new Set();
+    for (const value of features) {
+        if (!isFeatureKey(value)) {
+            throw new Error(`Unknown feature key: ${String(value)}`);
+        }
+        if (seen.has(value)) {
+            throw new Error(`Duplicate feature key: ${value}`);
+        }
+        seen.add(value);
+    }
+    return exports.FEATURE_CATALOG.filter((key) => seen.has(key));
+}
+/**
+ * Resolves the effective role for legacy documents without an explicit role.
+ *
+ * @param role - Stored role, if any.
+ */
+function resolveAdminRole(role) {
+    return role ?? 'admin';
+}
+/**
+ * Returns whether the user has admin-level unrestricted access.
+ *
+ * @param user - Authenticated or directory user.
+ */
+function isAdminUser(user) {
+    return resolveAdminRole(user.role) === 'admin';
+}
+/**
+ * Checks whether a user may access a feature.
+ *
+ * @param user - Authenticated user with role and feature grants.
+ * @param feature - Required feature key.
+ */
+function userHasFeature(user, feature) {
+    if (isAdminUser(user))
+        return true;
+    return user.features?.includes(feature) ?? false;
+}
+/**
+ * Checks whether a user may access at least one of the given features.
+ *
+ * @param user - Authenticated user with role and feature grants.
+ * @param features - Candidate feature keys.
+ */
+function userHasAnyFeature(user, features) {
+    if (isAdminUser(user))
+        return true;
+    return features.some((feature) => user.features?.includes(feature));
+}

package/dist/access.types.spec.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=access.types.spec.d.ts.map

package/dist/access.types.spec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"access.types.spec.d.ts","sourceRoot":"","sources":["../src/access.types.spec.ts"],"names":[],"mappings":""}

package/dist/access.types.spec.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const access_types_1 = require("./access.types");
+describe('access.types', () => {
+    it('recognizes valid feature keys', () => {
+        expect((0, access_types_1.isFeatureKey)('dashboard')).toBe(true);
+        expect((0, access_types_1.isFeatureKey)('unknown')).toBe(false);
+    });
+    it('normalizes feature keys in catalog order', () => {
+        expect((0, access_types_1.normalizeFeatureKeys)(['chat', 'site'])).toEqual(['site', 'chat']);
+    });
+    it('rejects duplicate feature keys', () => {
+        expect(() => (0, access_types_1.normalizeFeatureKeys)(['chat', 'site', 'chat'])).toThrow(/Duplicate feature key/);
+    });
+    it('rejects unknown feature keys', () => {
+        expect(() => (0, access_types_1.normalizeFeatureKeys)(['dashboard', 'billing'])).toThrow(/Unknown feature key/);
+    });
+    it('defaults missing roles to admin for legacy users', () => {
+        expect((0, access_types_1.resolveAdminRole)(undefined)).toBe('admin');
+        expect((0, access_types_1.resolveAdminRole)('guest')).toBe('guest');
+    });
+    it('grants admins every feature without explicit grants', () => {
+        const admin = { role: 'admin', features: [] };
+        expect((0, access_types_1.userHasFeature)(admin, 'system')).toBe(true);
+        expect((0, access_types_1.userHasAnyFeature)(admin, ['dashboard', 'launchpad'])).toBe(true);
+    });
+    it('requires explicit grants for guests', () => {
+        const guest = { role: 'guest', features: ['dashboard'] };
+        expect((0, access_types_1.userHasFeature)(guest, 'dashboard')).toBe(true);
+        expect((0, access_types_1.userHasFeature)(guest, 'system')).toBe(false);
+        expect((0, access_types_1.userHasAnyFeature)(guest, ['dashboard', 'launchpad'])).toBe(true);
+        expect((0, access_types_1.userHasAnyFeature)(guest, ['system', 'chat'])).toBe(false);
+    });
+    it('exposes a stable feature catalog', () => {
+        expect(access_types_1.FEATURE_CATALOG).toContain('users');
+        expect(access_types_1.FEATURE_CATALOG.length).toBe(9);
+    });
+});

package/dist/index.d.ts

@@ -8,6 +8,7 @@
  * @license MIT
  */
 export * from './auth.types';
+export * from './access.types';
 export * from './system.types';
 export * from './website.types';
 export * from './firestore.types';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,cAAc,CAAC;AAG7B,cAAc,4BAA4B,CAAC;AAG3C,cAAc,gBAAgB,CAAC;AAG/B,cAAc,cAAc,CAAC;AAG7B,cAAc,eAAe,CAAC;AAG9B,cAAc,eAAe,CAAC;AAG9B,cAAc,cAAc,CAAC;AAG7B,cAAc,mBAAmB,CAAC;AAGlC,YAAY,EAAE,QAAQ,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACxG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAGH,cAAc,cAAc,CAAC;AAG7B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,gBAAgB,CAAC;AAG/B,cAAc,iBAAiB,CAAC;AAGhC,cAAc,mBAAmB,CAAC;AAGlC,cAAc,2BAA2B,CAAC;AAG1C,cAAc,cAAc,CAAC;AAG7B,cAAc,4BAA4B,CAAC;AAG3C,cAAc,gBAAgB,CAAC;AAG/B,cAAc,cAAc,CAAC;AAG7B,cAAc,eAAe,CAAC;AAG9B,cAAc,eAAe,CAAC;AAG9B,cAAc,cAAc,CAAC;AAG7B,cAAc,mBAAmB,CAAC;AAGlC,YAAY,EAAE,QAAQ,EAAE,wBAAwB,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AACxG,OAAO,EAAE,aAAa,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -26,6 +26,8 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.SecurityLevel = void 0;
 // Auth types
 __exportStar(require("./auth.types"), exports);
+// Access control types
+__exportStar(require("./access.types"), exports);
 // System monitoring types
 __exportStar(require("./system.types"), exports);
 // Website/Site content types

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guinetik/primitives-ts",
-  "version": "0.8.2",
+  "version": "0.8.3",
   "description": "Shared TypeScript primitives for Guinetik projects",
   "author": "Guinetik",
   "license": "MIT",