mtlx-sdk 0.0.0-stage → 0.10.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ben Houston
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,175 @@
-# Temporary Holding Version
+[![Coverage](https://codecov.io/gh/bhouston/mtlx/branch/main/graph/badge.svg)](https://codecov.io/gh/bhouston/mtlx)
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# mtlx-sdk
+
+Official SDK for the [MTLX.ai](https://mtlx.ai) REST API.
+
+## Installation
+
+```bash
+npm install mtlx-sdk
+# or
+pnpm add mtlx-sdk
+# or
+yarn add mtlx-sdk
+```
+
+## Quick Start
+
+The SDK uses a **functional approach** - all API operations are exported as standalone functions that take a client instance as their first parameter. Every material belongs directly to a user (there are no organizations or projects).
+
+```typescript
+import { createSecretTokenInstance, listAssets, getAsset } from 'mtlx-sdk';
+
+const userName = 'alice';
+
+// Create a client instance (host defaults to https://api.mtlx.ai)
+const client = createSecretTokenInstance({
+  secretToken: 'your-api-token',
+});
+
+// List a user's materials
+const assets = await listAssets(client, {
+  query: { userName },
+});
+
+// Get a specific material
+const asset = await getAsset(client, {
+  params: { userName, assetName: 'copper' },
+});
+```
+
+## Features
+
+- **Functional API design** - All operations are exported as standalone functions
+- Full TypeScript support with complete type definitions
+- Zod schema validation for requests and responses
+- Axios-based HTTP client with automatic error handling
+- Support for all MTLX.ai API endpoints:
+  - Materials (MaterialX assets, always stored as `.mtlx.zip`)
+  - Users and authentication
+  - Comments and notifications
+  - File uploads and downloads
+  - API tokens
+
+## Uploading a Material
+
+The SDK provides a simple helper function for uploading files. Here's a complete example:
+
+```typescript
+import { readFile } from 'node:fs/promises';
+import { basename } from 'node:path';
+import { createSecretTokenInstance, uploadFile, createAsset } from 'mtlx-sdk';
+
+const userName = 'alice';
+
+const client = createSecretTokenInstance({
+  secretToken: 'your-api-token',
+});
+
+// Read the file and extract filename (loose `.mtlx` or packaged `.mtlx.zip`)
+const fileData = await readFile('copper.mtlx.zip');
+const filename = basename('copper.mtlx.zip');
+
+// Upload the file (infers MIME type and uploads)
+const uploadToken = await uploadFile(client, {
+  params: { userName },
+  fileData,
+  filename,
+});
+
+// Create the asset record with the upload token. The API validates the
+// MaterialX document during ingest and rejects malformed content with 400.
+const asset = await createAsset(client, {
+  params: { userName },
+  body: {
+    name: 'copper',
+    description: 'A brushed copper material',
+    type: 'MATERIAL',
+    uploadToken,
+    visibility: 'PUBLIC',
+    shareLicense: 'CC_BY',
+  },
+});
+```
+
+The `uploadFile` helper:
+
+- Accepts file data (Buffer or Uint8Array) and filename
+- Infers the MIME type from the file extension
+- Prepares the upload and gets a signed URL
+- Uploads the file to the signed URL
+- Returns the upload token for use in `createAsset`
+
+**Note:** In Node.js environments, you'll need to read the file yourself using `readFile` from `node:fs/promises` before calling `uploadFile`. In browser environments, you can pass a `File` object directly to `uploadFileToUploadUrl()` or convert it to an `ArrayBuffer`/`Uint8Array` for `uploadFile`.
+
+For more control, you can use `prepareAssetUpload()` and `uploadFileToUploadUrl()` directly.
+
+## API Reference
+
+### Client Configuration
+
+The SDK provides several client creation functions depending on your authentication method:
+
+```typescript
+import {
+  createSecretTokenInstance, // For API tokens (most common)
+  createFrontendTokenInstance, // For frontend tokens
+  createSessionInstance, // For user sessions
+  createAnonymousClient, // For anonymous access
+} from 'mtlx-sdk';
+
+// Most common: API token authentication
+// host defaults to 'https://api.mtlx.ai' if not provided
+const client = createSecretTokenInstance({
+  secretToken: 'your-api-token',
+  // host: 'https://api.mtlx.ai', // Optional, defaults to production API
+});
+```
+
+**Note:** For normal users, you typically don't need to specify the `host` parameter as it defaults to `https://api.mtlx.ai`. Only internal developers may need to override this for testing against different environments.
+
+### Available Functions
+
+The SDK exports functions for all API operations. Here are the main categories:
+
+**Assets (materials):**
+
+- `listAssets()` - List a user's materials (or search public ones)
+- `getAsset()` - Get material metadata, including the parsed `materialInfo`
+- `createAsset()` - Create a new material
+- `updateAsset()` - Update material metadata or replace its file
+- `deleteAsset()` - Delete a material
+- `uploadFile()` - Upload a file and get upload token (helper function)
+- `prepareAssetUpload()` - Get signed upload URL and token
+- `uploadFileToUploadUrl()` - Upload file to signed URL
+
+**Other resources:**
+
+- Users and authentication
+- Comments and notifications
+- API tokens
+
+All functions follow the pattern: `functionName(client, props)` where `client` is the API client instance and `props` contains the request parameters.
+
+## Zod Schemas
+
+The SDK exports Zod schemas for all API request and response types, enabling runtime validation:
+
+```typescript
+import { assetSchema, createAssetBodySchema } from 'mtlx-sdk';
+
+// Validate an asset object
+const validatedAsset = assetSchema.parse(assetData);
+
+// Validate create asset input
+const validatedInput = createAssetBodySchema.parse(createAssetInput);
+```
+
+## Requirements
+
+- Node.js >= 23.0.0
+
+## License
+
+MIT

package/dist/client.d.ts

@@ -0,0 +1,67 @@
+import { type AxiosInstance, type AxiosRequestConfig } from 'axios';
+import type * as z from 'zod';
+export type ApiAuthType = 'frontendToken' | 'access-token' | 'session' | 'anonymous';
+export type ApiAuthFrontendToken = {
+    authType: 'frontendToken';
+    frontendToken: string;
+};
+export type ApiAuthSecretToken = {
+    authType: 'secretToken';
+    secretToken: string;
+};
+export type ApiAuthUserSession = {
+    authType: 'userSession';
+    userSessionToken: string;
+};
+export type ApiAuthAnonymous = {
+    authType: 'anonymous';
+};
+export type ApiAuth = ApiAuthFrontendToken | ApiAuthSecretToken | ApiAuthUserSession | ApiAuthAnonymous;
+export type ApiClient = {
+    axios: AxiosInstance;
+    host: string;
+    auth: ApiAuth;
+    validateResults?: boolean;
+};
+export declare class ClientFetchError extends Error {
+    status: number;
+    constructor(message: string, status: number);
+}
+export type ApiRequest = {
+    path: string;
+    params?: Record<string, string | number | boolean | undefined>;
+    init?: Omit<AxiosRequestConfig, 'url' | 'params'>;
+};
+export type CreateInstanceParams = {
+    host: string;
+};
+export type CreateFrontendTokenInstanceParams = CreateInstanceParams & {
+    frontendToken: string;
+};
+export declare const createFrontendTokenInstance: ({ host, frontendToken }: CreateFrontendTokenInstanceParams) => ApiClient;
+export type CreateSecretTokenInstanceParams = CreateInstanceParams & {
+    secretToken: string;
+    accessToken?: string;
+};
+export declare const createSecretTokenInstance: ({ host, secretToken, accessToken, }: CreateSecretTokenInstanceParams) => ApiClient;
+export type CreateSessionInstanceParams = CreateInstanceParams & {
+    userSessionToken: string;
+    accessToken?: string;
+};
+export declare const createSessionInstance: ({ host, userSessionToken, accessToken, }: CreateSessionInstanceParams) => ApiClient;
+export type CreateAnonymousClientParams = CreateInstanceParams;
+export declare const createAnonymousClient: ({ host }: CreateAnonymousClientParams) => ApiClient;
+export declare const clientFetchUrl: (client: ApiClient, request: ApiRequest) => URL;
+export declare const clientFetch: (client: ApiClient, request: ApiRequest) => Promise<import("axios").AxiosResponse<any, any, {}, Record<string, string | number | boolean | undefined>>>;
+/**
+ * Conditionally parses API response data using a zod schema.
+ * If client.validateResults is true, validates and parses the data.
+ * Otherwise, returns the data with a type assertion based on the schema's inferred type.
+ *
+ * @param client - The API client instance (unused, kept for backward compatibility)
+ * @param schema - The zod schema to use for validation/type inference
+ * @param data - The raw response data to parse
+ * @returns The parsed or type-asserted data matching the schema's inferred type
+ */
+export declare const parseResult: <T extends z.ZodTypeAny>(client: ApiClient, schema: T, data: unknown) => z.infer<T>;
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sources":["../src/client.ts"],"names":[],"mappings":"AAAA,OAAc,EAAE,KAAK,aAAa,EAAE,KAAK,kBAAkB,EAAmC,MAAM,OAAO,CAAC;AAC5G,OAAO,KAAK,KAAK,CAAC,MAAM,KAAK,CAAC;AAK9B,MAAM,MAAM,WAAW,GAAG,eAAe,GAAG,cAAc,GAAG,SAAS,GAAG,WAAW,CAAC;AAGrF,MAAM,MAAM,oBAAoB,GAAG;IACjC,QAAQ,EAAE,eAAe,CAAC;IAC1B,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,aAAa,CAAC;IACxB,WAAW,EAAE,MAAM,CAAC;CACrB,CAAC;AAEF,MAAM,MAAM,kBAAkB,GAAG;IAC/B,QAAQ,EAAE,aAAa,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;CAC1B,CAAC;AAEF,MAAM,MAAM,gBAAgB,GAAG;IAC7B,QAAQ,EAAE,WAAW,CAAC;CACvB,CAAC;AAEF,MAAM,MAAM,OAAO,GAAG,oBAAoB,GAAG,kBAAkB,GAAG,kBAAkB,GAAG,gBAAgB,CAAC;AAExG,MAAM,MAAM,SAAS,GAAG;IACtB,KAAK,EAAE,aAAa,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,OAAO,CAAC;IACd,eAAe,CAAC,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,qBAAa,gBAAiB,SAAQ,KAAK;IACzC,MAAM,EAAE,MAAM,CAAC;IACf,YAAY,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAG1C;CACF;AAED,MAAM,MAAM,UAAU,GAAG;IACvB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,CAAC;IAC/D,IAAI,CAAC,EAAE,IAAI,CAAC,kBAAkB,EAAE,KAAK,GAAG,QAAQ,CAAC,CAAC;CACnD,CAAC;AAcF,MAAM,MAAM,oBAAoB,GAAG;IACjC,IAAI,EAAE,MAAM,CAAC;CACd,CAAC;AAEF,MAAM,MAAM,iCAAiC,GAAG,oBAAoB,GAAG;IACrE,aAAa,EAAE,MAAM,CAAC;CACvB,CAAC;AAEF,eAAO,MAAM,2BAA2B,4BAA6B,iCAAiC,KAAG,SAmBxG,CAAC;AAqDF,MAAM,MAAM,+BAA+B,GAAG,oBAAoB,GAAG;IACnE,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,eAAO,MAAM,yBAAyB,wCAInC,+BAA+B,KAAG,SASpC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG,oBAAoB,GAAG;IAC/D,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB,CAAC;AAEF,eAAO,MAAM,qBAAqB,6CAI/B,2BAA2B,KAAG,SAShC,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG,oBAAoB,CAAC;AAE/D,eAAO,MAAM,qBAAqB,aAAc,2BAA2B,KAAG,SAW7E,CAAC;AAEF,eAAO,MAAM,cAAc,WAAY,SAAS,WAAW,UAAU,QASpE,CAAC;AAEF,eAAO,MAAM,WAAW,WAAkB,SAAS,WAAW,UAAU,gHAQvE,CAAC;AAMF;;;;;;;;;GASG;AACH,eAAO,MAAM,WAAW,GAAI,CAAC,SAAS,CAAC,CAAC,UAAU,UAAU,SAAS,UAAU,CAAC,QAAQ,OAAO,KAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAC9D,CAAC"}

package/dist/client.js

@@ -0,0 +1,141 @@
+import axios from 'axios';
+import { makeUrl } from './lib/url.js';
+import { refreshAccessToken } from './routes/auth.js';
+export class ClientFetchError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+    }
+}
+const validateHost = (host) => {
+    if (!host.includes('://')) {
+        throw new Error(`host must include protocol, either http:// or https://, but it doesn't: ${host}`);
+    }
+};
+const validatePath = (path) => {
+    if (!path.startsWith('/api')) {
+        throw new Error(`path must start with "api", but it does not: ${path}`);
+    }
+};
+export const createFrontendTokenInstance = ({ host, frontendToken }) => {
+    validateHost(host);
+    // CDN friendly as it puts the public key in the URL.
+    const axiosInstance = axios.create({
+        baseURL: host,
+        params: {
+            frontendToken,
+        },
+    });
+    return {
+        axios: axiosInstance,
+        host,
+        auth: {
+            authType: 'frontendToken',
+            frontendToken,
+        },
+    };
+};
+const createJWTInstance = (host, refreshToken, accessToken) => {
+    validateHost(host);
+    const axiosInstance = axios.create({
+        baseURL: host,
+    });
+    // Set initial access token if provided
+    if (accessToken) {
+        axiosInstance.defaults.headers.common.Authorization = `Bearer ${accessToken}`;
+    }
+    const refresh = async (config) => {
+        const newAccessToken = await refreshAccessToken(host, {
+            body: {
+                refreshToken,
+            },
+        });
+        config.headers.set('Authorization', `Bearer ${newAccessToken.accessToken}`);
+        axiosInstance.defaults.headers.common.Authorization = `Bearer ${newAccessToken.accessToken}`;
+    };
+    axiosInstance.interceptors.request.use(async (config) => {
+        if (!config.headers.Authorization) {
+            await refresh(config);
+        }
+        return config;
+    });
+    axiosInstance.interceptors.response.use(async (response) => response, async (error) => {
+        const requestConfig = error.config;
+        // Only attempt refresh once per request
+        if (error.response?.status === 401 && !requestConfig._retried) {
+            requestConfig._retried = true;
+            await refresh(requestConfig);
+            // Retry the request once if refresh succeeded
+            return axiosInstance(requestConfig);
+        }
+        throw error;
+    });
+    return {
+        axios: axiosInstance,
+        host,
+    };
+};
+export const createSecretTokenInstance = ({ host, secretToken, accessToken, }) => {
+    validateHost(host);
+    return {
+        ...createJWTInstance(host, secretToken, accessToken),
+        auth: {
+            authType: 'secretToken',
+            secretToken,
+        },
+    };
+};
+export const createSessionInstance = ({ host, userSessionToken, accessToken, }) => {
+    validateHost(host);
+    return {
+        ...createJWTInstance(host, userSessionToken, accessToken),
+        auth: {
+            authType: 'userSession',
+            userSessionToken,
+        },
+    };
+};
+export const createAnonymousClient = ({ host }) => {
+    validateHost(host);
+    return {
+        axios: axios.create({
+            baseURL: host,
+        }),
+        host,
+        auth: {
+            authType: 'anonymous',
+        },
+    };
+};
+export const clientFetchUrl = (client, request) => {
+    validatePath(request.path);
+    let params = request.params;
+    if (client.auth.authType === 'frontendToken') {
+        params = { ...params, frontendToken: client.auth.frontendToken };
+    }
+    return makeUrl(client.host, request.path, params);
+};
+export const clientFetch = async (client, request) => {
+    validatePath(request.path);
+    return await client.axios.request({
+        ...request.init,
+        url: request.path,
+        params: request.params,
+    });
+};
+// Re-export parseResult from lib to maintain backward compatibility
+// This breaks the circular dependency since routes/auth.ts imports from lib/parseResult.ts directly
+import { parseResultWithClient } from './lib/parseResult.js';
+/**
+ * Conditionally parses API response data using a zod schema.
+ * If client.validateResults is true, validates and parses the data.
+ * Otherwise, returns the data with a type assertion based on the schema's inferred type.
+ *
+ * @param client - The API client instance (unused, kept for backward compatibility)
+ * @param schema - The zod schema to use for validation/type inference
+ * @param data - The raw response data to parse
+ * @returns The parsed or type-asserted data matching the schema's inferred type
+ */
+export const parseResult = (client, schema, data) => parseResultWithClient(client, schema, data);
+//# sourceMappingURL=client.js.map

package/dist/client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,26 @@
+export * from './client.js';
+export * from './lib/buildPath.js';
+export * from './lib/dashboardLinks.js';
+export * from './lib/enums.js';
+export * from './lib/eventRouter.js';
+export * from './lib/fileFormats.js';
+export * from './lib/list.js';
+export * from './lib/schemas.js';
+export * from './lib/types.js';
+export * from './lib/upload.js';
+export * from './lib/url.js';
+export * from './routes/apiTokens.js';
+export * from './routes/assets.js';
+export * from './routes/auth.js';
+export * from './routes/avatars.js';
+export * from './routes/comments.js';
+export * from './routes/error.js';
+export * from './routes/files.js';
+export * from './routes/health.js';
+export * from './routes/media.js';
+export * from './routes/notifications.js';
+export * from './routes/oembed.js';
+export * from './routes/serverEvents.js';
+export * from './routes/tasks.js';
+export * from './routes/users.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}

package/dist/index.js

@@ -0,0 +1,26 @@
+export * from './client.js';
+export * from './lib/buildPath.js';
+export * from './lib/dashboardLinks.js';
+export * from './lib/enums.js';
+export * from './lib/eventRouter.js';
+export * from './lib/fileFormats.js';
+export * from './lib/list.js';
+export * from './lib/schemas.js';
+export * from './lib/types.js';
+export * from './lib/upload.js';
+export * from './lib/url.js';
+export * from './routes/apiTokens.js';
+export * from './routes/assets.js';
+export * from './routes/auth.js';
+export * from './routes/avatars.js';
+export * from './routes/comments.js';
+export * from './routes/error.js';
+export * from './routes/files.js';
+export * from './routes/health.js';
+export * from './routes/media.js';
+export * from './routes/notifications.js';
+export * from './routes/oembed.js';
+export * from './routes/serverEvents.js';
+export * from './routes/tasks.js';
+export * from './routes/users.js';
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,aAAa,CAAC;AAC5B,cAAc,oBAAoB,CAAC;AACnC,cAAc,yBAAyB,CAAC;AACxC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,sBAAsB,CAAC;AACrC,cAAc,sBAAsB,CAAC;AACrC,cAAc,eAAe,CAAC;AAC9B,cAAc,kBAAkB,CAAC;AACjC,cAAc,gBAAgB,CAAC;AAC/B,cAAc,iBAAiB,CAAC;AAChC,cAAc,cAAc,CAAC;AAC7B,cAAc,uBAAuB,CAAC;AACtC,cAAc,oBAAoB,CAAC;AACnC,cAAc,kBAAkB,CAAC;AACjC,cAAc,qBAAqB,CAAC;AACpC,cAAc,sBAAsB,CAAC;AACrC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC;AAClC,cAAc,oBAAoB,CAAC;AACnC,cAAc,mBAAmB,CAAC;AAClC,cAAc,2BAA2B,CAAC;AAC1C,cAAc,oBAAoB,CAAC;AACnC,cAAc,0BAA0B,CAAC;AACzC,cAAc,mBAAmB,CAAC;AAClC,cAAc,mBAAmB,CAAC"}

package/dist/lib/buildPath.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Builds a path by replacing path parameters with their values.
+ * The params object is type-checked to match the parameters in the path string.
+ *
+ * @param path - Path template with parameters like `/api/$orgId/test`
+ * @param params - Object containing parameter values matching the path template
+ * @returns Resolved path with parameters substituted
+ *
+ * @example
+ * ```typescript
+ * buildPath('/users/$userName', { userName: 'john-doe' })
+ * // Returns: '/users/john-doe'
+ *
+ * // Type error if parameter is missing:
+ * buildPath('/users/$userName', {}) // Error: Property 'userName' is missing
+ * ```
+ */
+export declare const buildPath: (path: string, params: Record<string, string | number>) => string;
+//# sourceMappingURL=buildPath.d.ts.map

package/dist/lib/buildPath.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPath.d.ts","sources":["../../src/lib/buildPath.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,SAAS,SAAU,MAAM,UAAU,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,KAAG,MA6BjF,CAAC"}

package/dist/lib/buildPath.js

@@ -0,0 +1,46 @@
+// This should match paths like: /api/$orgId/test or /api/$orgId/$projectId/test
+const paramRegex = /\$(\w+)/g;
+/**
+ * Builds a path by replacing path parameters with their values.
+ * The params object is type-checked to match the parameters in the path string.
+ *
+ * @param path - Path template with parameters like `/api/$orgId/test`
+ * @param params - Object containing parameter values matching the path template
+ * @returns Resolved path with parameters substituted
+ *
+ * @example
+ * ```typescript
+ * buildPath('/users/$userName', { userName: 'john-doe' })
+ * // Returns: '/users/john-doe'
+ *
+ * // Type error if parameter is missing:
+ * buildPath('/users/$userName', {}) // Error: Property 'userName' is missing
+ * ```
+ */
+export const buildPath = (path, params) => {
+    // Collect all parameter names used in the path
+    const pathParams = new Set();
+    for (const match of path.matchAll(paramRegex)) {
+        const paramName = match[1]; // Extract parameter name without $ prefix (capture group)
+        if (paramName) {
+            pathParams.add(paramName);
+            // Check if param exists in params object
+            if (!(paramName in params)) {
+                throw new Error(`Param $${paramName} from path ${path} is not in the params object: ${JSON.stringify(params)}`);
+            }
+        }
+    }
+    // Check for unused parameters
+    const remainingParams = Object.keys(params).filter((key) => !pathParams.has(key));
+    if (remainingParams.length > 0) {
+        throw new Error(`Params ${remainingParams.join(', ')} from path ${path} are not all used: ${JSON.stringify(params)}`);
+    }
+    return path.replace(paramRegex, (_match, p1) => {
+        const param = params[p1];
+        if (param === undefined || param === null) {
+            throw new Error(`Param ${p1} from path ${path} is not in the params object: ${JSON.stringify(params)}`);
+        }
+        return encodeURIComponent(String(param));
+    });
+};
+//# sourceMappingURL=buildPath.js.map

package/dist/lib/buildPath.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildPath.js","sources":["../../src/lib/buildPath.ts"],"names":[],"mappings":"AAAA,gFAAgF;AAChF,MAAM,UAAU,GAAG,UAAU,CAAC;AAE9B;;;;;;;;;;;;;;;;GAgBG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,IAAY,EAAE,MAAuC,EAAU,EAAE;IACzF,+CAA+C;IAC/C,MAAM,UAAU,GAAG,IAAI,GAAG,EAAU,CAAC;IACrC,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC;QAC9C,MAAM,SAAS,GAAG,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,0DAA0D;QACtF,IAAI,SAAS,EAAE,CAAC;YACd,UAAU,CAAC,GAAG,CAAC,SAAS,CAAC,CAAC;YAC1B,yCAAyC;YACzC,IAAI,CAAC,CAAC,SAAS,IAAI,MAAM,CAAC,EAAE,CAAC;gBAC3B,MAAM,IAAI,KAAK,CAAC,UAAU,SAAS,cAAc,IAAI,iCAAiC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;YAClH,CAAC;QACH,CAAC;IACH,CAAC;IAED,8BAA8B;IAC9B,MAAM,eAAe,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,CAAC,UAAU,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,CAAC;IAClF,IAAI,eAAe,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CACb,UAAU,eAAe,CAAC,IAAI,CAAC,IAAI,CAAC,cAAc,IAAI,sBAAsB,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CACrG,CAAC;IACJ,CAAC;IAED,OAAO,IAAI,CAAC,OAAO,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,EAAE,EAAE,EAAE;QAC7C,MAAM,KAAK,GAAG,MAAM,CAAC,EAAE,CAAC,CAAC;QACzB,IAAI,KAAK,KAAK,SAAS,IAAI,KAAK,KAAK,IAAI,EAAE,CAAC;YAC1C,MAAM,IAAI,KAAK,CAAC,SAAS,EAAE,cAAc,IAAI,iCAAiC,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC;QAC1G,CAAC;QACD,OAAO,kBAAkB,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;AACL,CAAC,CAAC"}

package/dist/lib/dashboardLinks.d.ts

@@ -0,0 +1,19 @@
+export declare const dashboardUserLinkRegex: RegExp;
+export declare const dashboardAssetLinkRegex: RegExp;
+export declare const dashboardAssetCommentLinkRegex: RegExp;
+export declare const dashboardSettingsInvitesLinkRegex: RegExp;
+export declare const validDashboardLinkTargets: RegExp[];
+export declare function dashboardUserLink({ userName }: {
+    userName: string;
+}): string;
+export declare function dashboardAssetLink({ userName, assetName }: {
+    userName: string;
+    assetName: string;
+}): string;
+export declare function dashboardAssetCommentLink({ userName, assetName, commentHash, }: {
+    userName: string;
+    assetName: string;
+    commentHash: string;
+}): string;
+export declare function dashboardSettingsInvitesLink(): string;
+//# sourceMappingURL=dashboardLinks.d.ts.map

package/dist/lib/dashboardLinks.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboardLinks.d.ts","sources":["../../src/lib/dashboardLinks.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,sBAAsB,QAA0C,CAAC;AAC9E,eAAO,MAAM,uBAAuB,QAAiE,CAAC;AACtG,eAAO,MAAM,8BAA8B,QAE1C,CAAC;AACF,eAAO,MAAM,iCAAiC,QAA0B,CAAC;AAEzE,eAAO,MAAM,yBAAyB,EAAE,MAAM,EAK7C,CAAC;AASF,wBAAgB,iBAAiB,CAAC,EAAE,QAAQ,EAAE,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAG5E;AAED,wBAAgB,kBAAkB,CAAC,EAAE,QAAQ,EAAE,SAAS,EAAE,EAAE;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GAAG,MAAM,CAG3G;AAED,wBAAgB,yBAAyB,CAAC,EACxC,QAAQ,EACR,SAAS,EACT,WAAW,GACZ,EAAE;IACD,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,EAAE,MAAM,CAAC;IAClB,WAAW,EAAE,MAAM,CAAC;CACrB,GAAG,MAAM,CAGT;AAED,wBAAgB,4BAA4B,IAAI,MAAM,CAGrD"}

package/dist/lib/dashboardLinks.js

@@ -0,0 +1,37 @@
+import { coreEntityNameRegex } from './schemas.js';
+// Comment hash allows alphanumeric IDs (e.g. numeric comment.id or string "test")
+const commentHashRegex = '[a-zA-Z0-9][a-zA-Z0-9-]*';
+// Validation regexes for dashboard link paths (include leading slash to match actual link format)
+export const dashboardUserLinkRegex = new RegExp(`^/${coreEntityNameRegex}$`);
+export const dashboardAssetLinkRegex = new RegExp(`^/${coreEntityNameRegex}/${coreEntityNameRegex}$`);
+export const dashboardAssetCommentLinkRegex = new RegExp(`^/${coreEntityNameRegex}/${coreEntityNameRegex}#comment-${commentHashRegex}$`);
+export const dashboardSettingsInvitesLinkRegex = /^\/settings\/invites$/;
+export const validDashboardLinkTargets = [
+    dashboardUserLinkRegex,
+    dashboardAssetLinkRegex,
+    dashboardAssetCommentLinkRegex,
+    dashboardSettingsInvitesLinkRegex,
+];
+function validateAndReturn(path, regex) {
+    if (!regex.test(path)) {
+        throw new Error(`Invalid dashboard link: ${path}`);
+    }
+    return path;
+}
+export function dashboardUserLink({ userName }) {
+    const path = `/${userName}`;
+    return validateAndReturn(path, dashboardUserLinkRegex);
+}
+export function dashboardAssetLink({ userName, assetName }) {
+    const path = `/${userName}/${assetName}`;
+    return validateAndReturn(path, dashboardAssetLinkRegex);
+}
+export function dashboardAssetCommentLink({ userName, assetName, commentHash, }) {
+    const path = `/${userName}/${assetName}#comment-${commentHash}`;
+    return validateAndReturn(path, dashboardAssetCommentLinkRegex);
+}
+export function dashboardSettingsInvitesLink() {
+    const path = '/settings/invites';
+    return validateAndReturn(path, dashboardSettingsInvitesLinkRegex);
+}
+//# sourceMappingURL=dashboardLinks.js.map

package/dist/lib/dashboardLinks.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboardLinks.js","sources":["../../src/lib/dashboardLinks.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,cAAc,CAAC;AAEnD,kFAAkF;AAClF,MAAM,gBAAgB,GAAG,0BAA0B,CAAC;AAEpD,kGAAkG;AAClG,MAAM,CAAC,MAAM,sBAAsB,GAAG,IAAI,MAAM,CAAC,KAAK,mBAAmB,GAAG,CAAC,CAAC;AAC9E,MAAM,CAAC,MAAM,uBAAuB,GAAG,IAAI,MAAM,CAAC,KAAK,mBAAmB,IAAI,mBAAmB,GAAG,CAAC,CAAC;AACtG,MAAM,CAAC,MAAM,8BAA8B,GAAG,IAAI,MAAM,CACtD,KAAK,mBAAmB,IAAI,mBAAmB,YAAY,gBAAgB,GAAG,CAC/E,CAAC;AACF,MAAM,CAAC,MAAM,iCAAiC,GAAG,uBAAuB,CAAC;AAEzE,MAAM,CAAC,MAAM,yBAAyB,GAAa;IACjD,sBAAsB;IACtB,uBAAuB;IACvB,8BAA8B;IAC9B,iCAAiC;CAClC,CAAC;AAEF,SAAS,iBAAiB,CAAC,IAAY,EAAE,KAAa;IACpD,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,2BAA2B,IAAI,EAAE,CAAC,CAAC;IACrD,CAAC;IACD,OAAO,IAAI,CAAC;AACd,CAAC;AAED,MAAM,UAAU,iBAAiB,CAAC,EAAE,QAAQ,EAAwB;IAClE,MAAM,IAAI,GAAG,IAAI,QAAQ,EAAE,CAAC;IAC5B,OAAO,iBAAiB,CAAC,IAAI,EAAE,sBAAsB,CAAC,CAAC;AACzD,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,EAAE,QAAQ,EAAE,SAAS,EAA2C;IACjG,MAAM,IAAI,GAAG,IAAI,QAAQ,IAAI,SAAS,EAAE,CAAC;IACzC,OAAO,iBAAiB,CAAC,IAAI,EAAE,uBAAuB,CAAC,CAAC;AAC1D,CAAC;AAED,MAAM,UAAU,yBAAyB,CAAC,EACxC,QAAQ,EACR,SAAS,EACT,WAAW,GAKZ;IACC,MAAM,IAAI,GAAG,IAAI,QAAQ,IAAI,SAAS,YAAY,WAAW,EAAE,CAAC;IAChE,OAAO,iBAAiB,CAAC,IAAI,EAAE,8BAA8B,CAAC,CAAC;AACjE,CAAC;AAED,MAAM,UAAU,4BAA4B;IAC1C,MAAM,IAAI,GAAG,mBAAmB,CAAC;IACjC,OAAO,iBAAiB,CAAC,IAAI,EAAE,iCAAiC,CAAC,CAAC;AACpE,CAAC"}