@vibesdotdev/media 0.0.0-stage → 1.0.0-rc.3

package/dist/uploads/client/uploads-client.d.ts

@@ -0,0 +1,200 @@
+/**
+ * Uploads Client
+ *
+ * Runtime-resolved HTTP client for file uploads. Communicates with platform-web's
+ * storage endpoints at /api/storage/*.
+ *
+ * Cross-app upload access goes through getVibesUploadsClient(runtime) — never raw fetch
+ * against platform-web, never new UploadStorageService().
+ *
+ * Every id that reaches a URL is an opaque token and is percent-encoded into its
+ * path segment; every response is parsed by a schema; an error names the failed
+ * fact and the HTTP status, never the response body or any request value.
+ */
+import { CapabilityError, type KindContext, type VibesRuntime } from '@vibesdotdev/kernel';
+import { BaseRuntimeClient, type RuntimeClientDescriptor } from '@vibesdotdev/kernel/client';
+import { type UploadKind } from '../schemas/common.ts';
+import { type UploadClientOptions } from '../schemas/requests.ts';
+import { type CreateShareLinkOptions, type ShareLink } from '../schemas/shares.ts';
+export type UploadOptions = UploadClientOptions;
+export interface UploadResult {
+    id: string;
+    url: string;
+    name?: string;
+    contentType?: string;
+    size: number;
+    storagePath: string;
+}
+export interface FileRecord {
+    id: string;
+    title?: string;
+    filename: string;
+    originalFilename?: string;
+    mediaType?: string;
+    mimeType?: string;
+    fileSize: number;
+    isPublic: boolean;
+    storageProviderId?: string;
+    createdAt: string;
+    updatedAt: string;
+    thumbnailPath?: string;
+    width?: number;
+    height?: number;
+    url?: string;
+    thumbnailUrl?: string | null;
+}
+export interface StorageUsageResult {
+    totalFiles: number;
+    totalSize: number;
+    byKind: Record<UploadKind, {
+        files: number;
+        size: number;
+    }>;
+}
+/**
+ * Runtime-resolved uploads client extending BaseRuntimeClient.
+ *
+ * Communicates with apps/platform-web storage endpoints:
+ * - POST /api/storage/upload
+ * - GET /api/storage/files
+ * - GET /api/storage/files/[id]
+ * - DELETE /api/storage/files/[id]
+ */
+export declare class UploadsClient extends BaseRuntimeClient {
+    private apiBaseUrl;
+    private httpClient;
+    constructor(descriptor?: RuntimeClientDescriptor, context?: KindContext, runtime?: VibesRuntime);
+    protected onLoad(): Promise<void>;
+    dispose(): void;
+    /**
+     * Upload a file to storage.
+     *
+     * POSTs to platform-web's /api/storage/upload endpoint.
+     * Creates the canonical mediaItems row via platform-web.
+     */
+    upload(input: UploadOptions): Promise<UploadResult>;
+    /**
+     * Get file metadata for one or more file IDs.
+     *
+     * GETs from platform-web's /api/storage/files endpoint.
+     */
+    getFiles(ids: string[]): Promise<FileRecord[]>;
+    /**
+     * Get a single file's metadata.
+     *
+     * Calls the JSON metadata endpoint (/api/storage/files/[id]/meta) rather than
+     * issuing a HEAD against the binary-download route. The download route returns
+     * a binary stream (or 302 redirect) and does not expose filename or MIME type
+     * in headers, so a HEAD request cannot populate a usable FileRecord.
+     */
+    getFile(id: string, serviceToken?: string): Promise<FileRecord | null>;
+    /**
+     * Get the public serve URL for a file.
+     *
+     * Returns the path that can be used to serve/download the file.
+     */
+    getServeUrl(fileId: string): string;
+    /**
+     * Create a revocable, public share link for a file (owner-only).
+     *
+     * POSTs to platform-web's `/api/storage/files/[id]/shares`. The returned
+     * `shareUrl` is an absolute, anonymously-fetchable URL pointing at the
+     * session-bypassed `/api/storage/shared/[token]` serving route — never the
+     * private files/[id] path. Egress on share downloads is billed to the owner.
+     */
+    createShareLink(fileId: string, options?: CreateShareLinkOptions): Promise<ShareLink>;
+    /**
+     * List active + revoked share links for a file (owner-only).
+     *
+     * GETs from platform-web's `/api/storage/files/[id]/shares`.
+     */
+    listShareLinks(fileId: string): Promise<ShareLink[]>;
+    /**
+     * Revoke a share link (owner-only). Soft-revokes server-side so audit data
+     * survives. Returns false when the link does not exist or is not owned.
+     *
+     * DELETEs platform-web's `/api/storage/files/[id]/shares/[shareId]`.
+     */
+    revokeShareLink(fileId: string, shareId: string): Promise<boolean>;
+    /**
+     * Assert that a file is owned by a specific user.
+     *
+     * Uses the /meta endpoint with an optional service token for server-to-server
+     * calls. Compares the file's userId field (returned in the JSON metadata)
+     * against the supplied userId. The X-User-Id header approach is not used
+     * because platform-web never reads that header for authorization.
+     *
+     * Any failure (a refused id, a failed request, an unreadable answer) is "not
+     * owned": the check fails closed and logs the failure's class only.
+     *
+     * @param fileId  - The file ID to check.
+     * @param userId  - The user ID to compare against the file's owner.
+     * @param serviceToken - Optional VIBES_INTERNAL_SERVICE_TOKEN for server-side
+     *   calls made without a forwarded user session cookie.
+     */
+    assertOwnedBy(fileId: string, userId: string, serviceToken?: string): Promise<boolean>;
+    /**
+     * Delete a file.
+     *
+     * DELETEs from platform-web's /api/storage/files/[id] endpoint.
+     */
+    delete(fileId: string): Promise<boolean>;
+    /**
+     * Storage usage for a user.
+     *
+     * platform-web exposes no usage endpoint to this client, so there is no
+     * answer to give: the call refuses (`upload-usage-unavailable`) instead of
+     * answering zeros that a caller would read as "nothing stored". Query
+     * platform-web directly for usage.
+     */
+    getUserStorageUsage(_userId: string): Promise<StorageUsageResult>;
+    /**
+     * Refuse an upload that cannot succeed, before any request: unknown kind,
+     * empty provenance, a size or type the package forbids, a size over the
+     * caller's own cap, or a type outside the caller's own allowlist.
+     */
+    private validateUploadOptions;
+    /** The response's JSON body, parsed by `schema`; an unreadable or mismatching body is `upload-response-invalid`. */
+    private readJson;
+    /**
+     * Build the upload URL with query parameters.
+     */
+    private buildUploadUrl;
+    /**
+     * Cookie-authenticated requests carry session cookies so the catalogued
+     * platform origin can authenticate the browser user even when that origin
+     * differs from the page origin (cross-origin deployments must also allow
+     * the credentials on the platform side). Service-token requests carry their
+     * own Authorization identity instead, so they never depend on cookies.
+     */
+    private crossOriginCookieInit;
+    /**
+     * Resolve the uploads API base URL from the `platform` service catalog.
+     * When that service is undeclared, the browser page origin is the host fact.
+     */
+    private resolveUploadsApiBaseUrl;
+    /**
+     * Perform a fetch request.
+     */
+    private fetch;
+}
+/**
+ * Error thrown by UploadsClient: a `CapabilityError` whose code follows the
+ * HTTP status, carrying `status` and a `reason`, naming no response body.
+ */
+export declare class UploadsClientError extends CapabilityError {
+    readonly status?: number;
+    constructor(message: string, options?: {
+        status?: number;
+        reason?: string;
+        cause?: Error;
+    });
+}
+/**
+ * Create an uploads client instance directly.
+ *
+ * Prefer getVibesUploadsClient(runtime) for runtime-resolved access.
+ */
+export declare function createUploadsClient(runtime?: VibesRuntime, context?: KindContext): UploadsClient;
+export default UploadsClient;
+//# sourceMappingURL=uploads-client.d.ts.map

package/dist/uploads/client/uploads-client.d.ts.map

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