@mosano-product-framework/sdk 0.2.0

package/dist/react/store.d.ts

@@ -0,0 +1,85 @@
+/**
+ * A tiny external store for `useSyncExternalStore`.
+ *
+ * Zero dependencies and no tearing: `useSyncExternalStore` is React's own
+ * contract for reading external mutable state, so concurrent rendering cannot
+ * observe two different snapshots within one commit. A `useState` +
+ * `useEffect` mirror would.
+ *
+ * `getSnapshot` must return a **referentially stable** value while nothing has
+ * changed, or React re-renders forever. Every mutation here therefore builds
+ * exactly one new state object and every non-mutation returns the existing one.
+ */
+import type { MPFClaims } from '../auth/claims-types.js';
+import type { TenantSelection } from '../auth/tenant-selection.js';
+import type { TenantDirectoryEntry } from '../auth/tenant-directory.js';
+/**
+ * Whether the selectable-tenant list is known.
+ *
+ * Only two states, because this list comes from the access token's claims: if
+ * there is a token the answer is known, and if there is not, it is not. There is
+ * no fetch, so there is nothing to fail. The thing that CAN fail is the display
+ * name lookup — see {@link TenantDirectoryStatus}, which is where the
+ * "loaded-but-empty vs failed" distinction actually earns its keep.
+ */
+export type TenantsStatus = 'unloaded' | 'loaded';
+/** Whether tenant display names have been fetched. */
+export type TenantDirectoryStatus = 'unloaded' | 'loading' | 'loaded' | 'failed';
+/** A tenant as surfaced to the UI. */
+export interface TenantEntry {
+    id: string;
+    /** Every role held in this tenant. */
+    roles: string[];
+    /**
+     * That tenant's default role: its explicit `dfr` claim when the token carries
+     * one, otherwise `roles[0]`. Absent only when the tenant grants no roles.
+     *
+     * Surfaced separately because `roles[0]` is no longer authoritative — a token
+     * may name a default that is not the first role listed.
+     */
+    defaultRole?: string;
+    /**
+     * Display name, present only once the directory has loaded. Render
+     * `name ?? id` so a switcher degrades to the id rather than to nothing.
+     */
+    name?: string;
+    /** URL-friendly slug, present only once the directory has loaded. */
+    slug?: string;
+}
+export interface AuthState {
+    /** True once hydration has run. Always true after provider construction. */
+    hydrated: boolean;
+    /** True when an access token is present. */
+    authenticated: boolean;
+    /** Decoded (UNVERIFIED, UX-only) claims of the current access token. */
+    claims: MPFClaims | null;
+    /** Current tenant selection. */
+    selection: TenantSelection;
+    /** Whether the selectable-tenant list is known (i.e. whether a token exists). */
+    tenantsStatus: TenantsStatus;
+    /** Selectable tenants, meaningful only when `tenantsStatus === 'loaded'`. */
+    tenants: TenantEntry[];
+    /**
+     * Display-name lookup state.
+     *
+     * Tri-state on purpose: "this user belongs to zero tenants" and "we could not
+     * find out what they are called" must never be indistinguishable. Collapsing
+     * them is a real bug class — an empty switcher that silently means "the server
+     * was unreachable".
+     */
+    directoryStatus: TenantDirectoryStatus;
+    /** Fetched display metadata, keyed by tenant id. */
+    directory: Record<string, TenantDirectoryEntry>;
+    /** Why the directory fetch failed, when it did. */
+    directoryError: Error | null;
+}
+export interface AuthStore {
+    getSnapshot(): AuthState;
+    subscribe(listener: () => void): () => void;
+    setState(patch: Partial<AuthState>): void;
+}
+export declare function createInitialState(overrides?: Partial<AuthState>): AuthState;
+/**
+ * Create an auth store.
+ */
+export declare function createAuthStore(initial: AuthState): AuthStore;

package/dist/storage/index.d.ts

@@ -0,0 +1,31 @@
+import type { StorageClientOptions } from './types.js';
+import { StorageClientV0 } from './v0.js';
+/**
+ * Creates a Storage client for API v0
+ *
+ * @param options - Client configuration options
+ * @returns StorageClientV0 instance
+ *
+ * @example
+ * ```typescript
+ * import { createStorageClient } from '@mosano-product-framework/sdk/storage';
+ *
+ * // Create authenticated storage client
+ * const storage = createStorageClient({
+ *   baseUrl: 'https://api.example.com/storage',
+ *   tokenProvider: {
+ *     getAccessToken: () => localStorage.getItem('accessToken'),
+ *     onTokenExpired: () => { window.location.href = '/login'; },
+ *   },
+ * });
+ *
+ * // Upload a file
+ * const metadata = await storage.uploadFile(myFile);
+ *
+ * // Get a download URL
+ * const { url } = await storage.getDownloadSignedUrl(metadata.id);
+ * ```
+ */
+export declare function createStorageClient(options: StorageClientOptions): StorageClientV0;
+export { StorageClientV0 } from './v0.js';
+export * from './types.js';

package/dist/storage/index.js

@@ -0,0 +1,5 @@
+export { StorageClientV0, createStorageClient } from '../chunk-EXPYHNPV.js';
+import '../chunk-LRM6JJ63.js';
+import '../chunk-AJWM5MDZ.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/storage/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}

package/dist/storage/types.d.ts

@@ -0,0 +1,107 @@
+import type { TokenProvider } from '../client/core/types.js';
+import type { Middleware } from '../client/core/middleware.js';
+/**
+ * Configuration options for the Storage client
+ */
+export interface StorageClientOptions {
+    /** Base URL for the Storage service */
+    baseUrl: string;
+    /** Optional token provider. Auto-wires auth middleware when provided. */
+    tokenProvider?: TokenProvider;
+    /**
+     * Optional shared tenant selection. Auto-wires the tenant middleware when
+     * provided. Share one `createTenantSelection()` instance across clients.
+     */
+    tenantProvider?: import('../auth/tenant-selection.js').TenantSelectionStore;
+    /** Default headers to include in all requests */
+    headers?: Record<string, string>;
+    /** Middlewares to apply to all requests */
+    middlewares?: Middleware[];
+}
+/**
+ * File metadata returned by the storage service
+ */
+export interface FileMetadataResponse {
+    /** File's unique identifier */
+    id: string;
+    /** Original file name */
+    name?: string;
+    /** File size in bytes */
+    size?: number;
+    /** MIME type of the file */
+    mime_type?: string;
+    /** Entity tag for cache validation */
+    etag?: string;
+    /** Current upload status */
+    upload_status: string;
+    /** When the file expires (ISO 8601) */
+    expires_at?: string;
+    /** When the file was created (ISO 8601) */
+    created_at: string;
+    /** When the file was last updated (ISO 8601) */
+    updated_at: string;
+}
+/**
+ * Response containing a signed URL for file upload
+ */
+export interface UploadSignedUrlResponse {
+    /** File ID for the pending upload */
+    file_id: string;
+    /** Signed URL to upload the file to */
+    url: string;
+}
+/**
+ * Response containing a signed URL for file download
+ */
+export interface DownloadSignedUrlResponse {
+    /** Signed URL to download the file from */
+    url: string;
+    /** Optional file metadata */
+    metadata?: FileMetadataResponse;
+}
+/**
+ * Request body for getting a single upload signed URL
+ */
+export interface GetUploadSignedUrlRequest {
+    /** File name */
+    name: string;
+    /** MIME type of the file */
+    mime_type: string;
+}
+/**
+ * Request body for getting multiple upload signed URLs
+ */
+export interface GetBatchUploadSignedUrlsRequest {
+    /** Array of file descriptors */
+    files: GetUploadSignedUrlRequest[];
+}
+/**
+ * Request body for getting multiple download signed URLs
+ */
+export interface GetBatchDownloadSignedUrlsRequest {
+    /** Array of file IDs to download */
+    file_ids: string[];
+}
+/**
+ * Request body for batch deleting files
+ */
+export interface BatchDeleteFilesRequest {
+    /** Array of file IDs to delete */
+    file_ids: string[];
+}
+/**
+ * Request body for batch confirming uploads
+ */
+export interface BatchConfirmUploadsRequest {
+    /** Array of file IDs to confirm */
+    file_ids: string[];
+}
+/**
+ * Entry for batch file replacement
+ */
+export interface BatchReplaceFilesEntry {
+    /** ID of the file to replace */
+    fileId: string;
+    /** New file content */
+    file: Blob | File;
+}

package/dist/storage/v0.d.ts

@@ -0,0 +1,120 @@
+import { MPFClient } from '../client/core/client.js';
+import type { RequestOptions } from '../client/core/types.js';
+import type { StorageClientOptions, FileMetadataResponse, UploadSignedUrlResponse, DownloadSignedUrlResponse, GetUploadSignedUrlRequest, GetBatchUploadSignedUrlsRequest, GetBatchDownloadSignedUrlsRequest, BatchDeleteFilesRequest, BatchConfirmUploadsRequest, BatchReplaceFilesEntry } from './types.js';
+/**
+ * Storage API v0 client
+ *
+ * Provides methods for file upload, download, confirmation, deletion,
+ * and replacement using both signed URLs and direct multipart uploads.
+ */
+export declare class StorageClientV0 extends MPFClient {
+    constructor(options: StorageClientOptions);
+    /**
+     * Get a signed URL for uploading a single file
+     *
+     * @param data - File name and MIME type
+     * @param options - Optional request options
+     * @returns Signed URL and file ID
+     */
+    getUploadSignedUrl(data: GetUploadSignedUrlRequest, options?: RequestOptions): Promise<UploadSignedUrlResponse>;
+    /**
+     * Get signed URLs for uploading multiple files
+     *
+     * @param data - Array of file descriptors
+     * @param options - Optional request options
+     * @returns Array of signed URLs and file IDs
+     */
+    getBatchUploadSignedUrls(data: GetBatchUploadSignedUrlsRequest, options?: RequestOptions): Promise<UploadSignedUrlResponse[]>;
+    /**
+     * Upload a single file via multipart form data
+     *
+     * @param file - The file or blob to upload
+     * @param options - Optional request options
+     * @returns File metadata
+     */
+    uploadFile(file: Blob | File, options?: RequestOptions): Promise<FileMetadataResponse>;
+    /**
+     * Upload multiple files via multipart form data
+     *
+     * @param files - Array of files or blobs to upload
+     * @param options - Optional request options
+     * @returns Array of file metadata
+     */
+    batchUploadFiles(files: (Blob | File)[], options?: RequestOptions): Promise<FileMetadataResponse[]>;
+    /**
+     * Get a signed URL for downloading a file
+     *
+     * @param fileId - The file ID
+     * @param options - Optional request options
+     * @returns Signed download URL and optional metadata
+     */
+    getDownloadSignedUrl(fileId: string, options?: RequestOptions): Promise<DownloadSignedUrlResponse>;
+    /**
+     * Get signed URLs for downloading multiple files
+     *
+     * @param data - Array of file IDs
+     * @param options - Optional request options
+     * @returns Array of signed download URLs
+     */
+    getBatchDownloadSignedUrls(data: GetBatchDownloadSignedUrlsRequest, options?: RequestOptions): Promise<DownloadSignedUrlResponse[]>;
+    /**
+     * Confirm a single file upload
+     *
+     * @param fileId - The file ID to confirm
+     * @param options - Optional request options
+     * @returns Updated file metadata
+     */
+    confirmUpload(fileId: string, options?: RequestOptions): Promise<FileMetadataResponse>;
+    /**
+     * Confirm multiple file uploads
+     *
+     * @param data - Array of file IDs to confirm
+     * @param options - Optional request options
+     * @returns Array of updated file metadata
+     */
+    batchConfirmUploads(data: BatchConfirmUploadsRequest, options?: RequestOptions): Promise<FileMetadataResponse[]>;
+    /**
+     * Delete a single file
+     *
+     * @param fileId - The file ID to delete
+     * @param options - Optional request options
+     * @returns Deleted file metadata
+     */
+    deleteFile(fileId: string, options?: RequestOptions): Promise<FileMetadataResponse>;
+    /**
+     * Delete multiple files
+     *
+     * @param data - Array of file IDs to delete
+     * @param options - Optional request options
+     * @returns Array of deleted file metadata
+     */
+    batchDeleteFiles(data: BatchDeleteFilesRequest, options?: RequestOptions): Promise<FileMetadataResponse[]>;
+    /**
+     * Replace a single file via multipart form data
+     *
+     * @param fileId - The file ID to replace
+     * @param file - The new file or blob
+     * @param options - Optional request options
+     * @returns Updated file metadata
+     */
+    replaceFile(fileId: string, file: Blob | File, options?: RequestOptions): Promise<FileMetadataResponse>;
+    /**
+     * Replace multiple files via multipart form data
+     *
+     * @param replacements - Array of file ID and new file pairs
+     * @param options - Optional request options
+     * @returns Array of updated file metadata
+     */
+    batchReplaceFiles(replacements: BatchReplaceFilesEntry[], options?: RequestOptions): Promise<FileMetadataResponse[]>;
+    /**
+     * Execute a multipart/form-data request.
+     *
+     * Delegates to `MPFClient.request()` so multipart uploads get the same
+     * middleware chain and retry loop as every other request. `request()` drops
+     * the default JSON `Content-Type` for a `FormData` body so that fetch sets
+     * `multipart/form-data` with the correct boundary string.
+     *
+     * `FormData` is re-readable, so a failed upload is safely retryable.
+     */
+    private multipartRequest;
+}

package/package.json

@@ -0,0 +1,99 @@
+{
+  "name": "@mosano-product-framework/sdk",
+  "version": "0.2.0",
+  "description": "MPF SDK: typed clients for the MPF services",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./client": {
+      "types": "./dist/client/index.d.ts",
+      "import": "./dist/client/index.js"
+    },
+    "./auth": {
+      "types": "./dist/auth/index.d.ts",
+      "import": "./dist/auth/index.js"
+    },
+    "./identity": {
+      "types": "./dist/identity/index.d.ts",
+      "import": "./dist/identity/index.js"
+    },
+    "./storage": {
+      "types": "./dist/storage/index.d.ts",
+      "import": "./dist/storage/index.js"
+    },
+    "./react": {
+      "types": "./dist/react/index.d.ts",
+      "import": "./dist/react/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsup && tsc -p tsconfig.build.json",
+    "dev": "tsup --watch",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.test.json",
+    "lint": "eslint .",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "verify:dist": "tsc --noEmit --skipLibCheck false --strict --target ES2022 --module ESNext --moduleResolution bundler --lib ES2022,DOM dist/index.d.ts dist/client/index.d.ts dist/auth/index.d.ts dist/identity/index.d.ts dist/storage/index.d.ts dist/react/index.d.ts",
+    "prepublishOnly": "pnpm build"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9",
+    "@testing-library/dom": "^10.0.0",
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^20.0.0",
+    "@types/react": "^18.3.12",
+    "eslint": "^9",
+    "graphql": "^16.9.0",
+    "graphql-ws": "^5.16.0",
+    "jsdom": "^25.0.1",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0",
+    "typescript-eslint": "^8",
+    "vitest": "^2.1.9"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0",
+    "graphql": "^16.0.0",
+    "graphql-ws": "^5.14.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    },
+    "graphql": {
+      "optional": true
+    },
+    "graphql-ws": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "keywords": [
+    "mpf",
+    "sdk",
+    "auth"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://gitlab.com/mosano-product-framework/services.git",
+    "directory": "pkg/js-sdk"
+  },
+  "dependencies": {
+    "jose": "^6.2.3"
+  }
+}