@constructive-io/graphql-query 4.14.1 → 4.15.0

package/esm/index.js

@@ -29,5 +29,7 @@ export * from './generators';
 export * from './client';
 // Introspection utilities (infer-tables, transform, transform-schema, schema-query)
 export * from './introspect';
+// Dynamic storage client (discover planes from _meta, build upload documents)
+export * from './storage';
 // Utility functions
 export { parseSmartTags, stripSmartComments } from './utils';

package/esm/meta-object/convert.js

@@ -13,6 +13,7 @@ export function convertFromMetaSchema(metaSchema) {
             primaryConstraints: pickArrayConstraint(table.primaryKeyConstraints),
             uniqueConstraints: pickArrayConstraint(table.uniqueConstraints),
             foreignConstraints: pickForeignConstraint(table.foreignKeyConstraints, table.relations),
+            ...(table.storage ? { storage: table.storage } : {}),
         });
     }
     return result;

package/esm/storage/client.js

@@ -0,0 +1,30 @@
+/**
+ * Runtime dynamic storage client — a thin composition of the three modular
+ * pieces: `_meta` discovery, document building, and upload orchestration.
+ *
+ * The caller never names a mutation, input type, or bucket query field.
+ */
+import { findStorageSurface, resolveStorageSurfaces, STORAGE_META_QUERY } from './meta';
+import { uploadToSurface } from './upload';
+export function createStorageClient(options) {
+    const { execute, transport } = options;
+    let cachedSurfaces = null;
+    async function discover() {
+        if (cachedSurfaces)
+            return cachedSurfaces;
+        const result = (await execute(STORAGE_META_QUERY, {}));
+        cachedSurfaces = resolveStorageSurfaces(result);
+        return cachedSurfaces;
+    }
+    async function surface(selector) {
+        return findStorageSurface(await discover(), selector);
+    }
+    async function upload(selector, uploadOptions) {
+        if (!transport) {
+            throw new Error('STORAGE_TRANSPORT_MISSING: createStorageClient({ transport }) is required to upload; ' +
+                'pass the adapter from @constructive-io/upload-client or your own StorageTransport');
+        }
+        return uploadToSurface(await surface(selector), uploadOptions, { execute, transport });
+    }
+    return { discover, surface, upload };
+}

package/esm/storage/document.js

@@ -0,0 +1,98 @@
+/**
+ * Dynamic GraphQL document construction for storage surfaces.
+ *
+ * Every name in the emitted document comes from the plane's `_meta`-reported
+ * surface — nothing here assembles or guesses a GraphQL name.
+ */
+import * as t from 'gql-ast';
+import { OperationTypeNode, print } from 'graphql';
+const UPLOAD_PAYLOAD_FIELDS = [
+    'uploadUrl',
+    'fileId',
+    'key',
+    'deduplicated',
+    'expiresAt',
+    'previousVersionId',
+];
+/**
+ * Build the single-file upload mutation document for a storage plane:
+ *
+ *   mutation UploadAppFileMutation($input: UploadAppFileInput!) {
+ *     uploadAppFile(input: $input) {
+ *       uploadUrl fileId key deduplicated expiresAt previousVersionId
+ *     }
+ *   }
+ */
+export function buildUploadDocument(surface) {
+    const { mutation, inputType } = surface.upload;
+    const ast = t.document({
+        definitions: [
+            t.operationDefinition({
+                operation: OperationTypeNode.MUTATION,
+                name: `${capitalize(mutation)}Mutation`,
+                variableDefinitions: [
+                    t.variableDefinition({
+                        variable: t.variable({ name: 'input' }),
+                        type: t.nonNullType({ type: t.namedType({ type: inputType }) }),
+                    }),
+                ],
+                selectionSet: t.selectionSet({
+                    selections: [
+                        t.field({
+                            name: mutation,
+                            args: [t.argument({ name: 'input', value: t.variable({ name: 'input' }) })],
+                            selectionSet: t.selectionSet({
+                                selections: UPLOAD_PAYLOAD_FIELDS.map((name) => t.field({ name })),
+                            }),
+                        }),
+                    ],
+                }),
+            }),
+        ],
+    });
+    return print(ast);
+}
+/**
+ * Build the download-URL query document for a file row on a storage plane,
+ * looked up through the files type's single-row query field reported by
+ * `_meta` (`query.one`, e.g. `appFile`), selecting the plane's computed
+ * download field.
+ */
+export function buildDownloadUrlDocument(surface) {
+    if (!surface.downloadUrlField) {
+        throw new Error(`STORAGE_SURFACE_NO_DOWNLOAD_FIELD: plane ${surface.filesType} reports no download-URL field`);
+    }
+    const nodeField = surface.filesNodeField;
+    if (!nodeField) {
+        throw new Error(`STORAGE_SURFACE_NO_NODE_FIELD: plane ${surface.filesType} reports no single-row query field`);
+    }
+    const ast = t.document({
+        definitions: [
+            t.operationDefinition({
+                operation: OperationTypeNode.QUERY,
+                name: `${surface.filesType}DownloadUrlQuery`,
+                variableDefinitions: [
+                    t.variableDefinition({
+                        variable: t.variable({ name: 'id' }),
+                        type: t.nonNullType({ type: t.namedType({ type: 'UUID' }) }),
+                    }),
+                ],
+                selectionSet: t.selectionSet({
+                    selections: [
+                        t.field({
+                            name: nodeField,
+                            args: [t.argument({ name: 'id', value: t.variable({ name: 'id' }) })],
+                            selectionSet: t.selectionSet({
+                                selections: [t.field({ name: 'id' }), t.field({ name: surface.downloadUrlField })],
+                            }),
+                        }),
+                    ],
+                }),
+            }),
+        ],
+    });
+    return print(ast);
+}
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}

package/esm/storage/index.js

@@ -0,0 +1,5 @@
+export { createStorageClient } from './client';
+export { buildDownloadUrlDocument, buildUploadDocument } from './document';
+export { findStorageSurface, resolveStorageSurfaces, STORAGE_META_QUERY } from './meta';
+export { StorageError } from './transport';
+export { uploadToSurface } from './upload';

package/esm/storage/meta.js

@@ -0,0 +1,123 @@
+/**
+ * Storage-surface discovery from the `_meta` root query.
+ *
+ * `_meta` is the semantic storage contract: graphile-meta reports each storage
+ * plane's paired tables and upload surface from the registry's own FK facts,
+ * so resolving here can never disagree with the emitted schema.
+ */
+/** The `_meta` selection a dynamic storage client needs. */
+export const STORAGE_META_QUERY = `
+query StorageMeta {
+  _meta {
+    tables {
+      name
+      tableName
+      schemaName
+      query {
+        one
+      }
+      storage {
+        isFilesTable
+        isBucketsTable
+        filesType
+        bucketsType
+        downloadUrlField
+        upload {
+          mutation
+          inputType
+          payloadType
+          bulkMutation
+          bulkInputType
+          bulkPayloadType
+          bulkFileInputType
+          bulkFilePayloadType
+          requiresOwnerId
+        }
+      }
+    }
+  }
+}
+`.trim();
+/**
+ * Resolve every storage plane from a `_meta` response. Both sides of a plane
+ * (files and buckets tables) report the same surface; this pairs them back up
+ * and fails loudly on any inconsistency rather than returning a partial plane.
+ */
+export function resolveStorageSurfaces(result) {
+    const tables = result?._meta?.tables;
+    if (!Array.isArray(tables)) {
+        throw new Error('STORAGE_META_MALFORMED: _meta.tables missing from response');
+    }
+    const filesByType = new Map();
+    const bucketsByType = new Map();
+    for (const table of tables) {
+        if (!table.storage)
+            continue;
+        const { isFilesTable, isBucketsTable, filesType } = table.storage;
+        if (isFilesTable) {
+            const existing = filesByType.get(filesType);
+            if (existing) {
+                throw new Error(`STORAGE_META_MALFORMED: two files tables (${existing.schemaName}.${existing.tableName}, ` +
+                    `${table.schemaName}.${table.tableName}) report the same plane ${filesType}`);
+            }
+            filesByType.set(filesType, table);
+        }
+        else if (isBucketsTable) {
+            const existing = bucketsByType.get(filesType);
+            if (existing) {
+                throw new Error(`STORAGE_META_MALFORMED: two buckets tables (${existing.schemaName}.${existing.tableName}, ` +
+                    `${table.schemaName}.${table.tableName}) report the same plane ${filesType}`);
+            }
+            bucketsByType.set(filesType, table);
+        }
+        else {
+            throw new Error(`STORAGE_META_MALFORMED: table ${table.schemaName}.${table.tableName} carries storage ` +
+                `metadata but is neither a files nor a buckets table`);
+        }
+    }
+    for (const [filesType, bucketsTable] of bucketsByType) {
+        if (!filesByType.has(filesType)) {
+            throw new Error(`STORAGE_META_MALFORMED: buckets table ${bucketsTable.schemaName}.${bucketsTable.tableName} ` +
+                `reports plane ${filesType} but no files table does`);
+        }
+    }
+    const surfaces = [];
+    for (const [filesType, filesTable] of filesByType) {
+        const storage = filesTable.storage;
+        const bucketsTable = bucketsByType.get(filesType) ?? null;
+        surfaces.push({
+            filesType,
+            bucketsType: storage.bucketsType,
+            filesTable: tableRef(filesTable),
+            bucketsTable: bucketsTable ? tableRef(bucketsTable) : null,
+            filesNodeField: filesTable.query?.one ?? null,
+            downloadUrlField: storage.downloadUrlField,
+            upload: storage.upload,
+        });
+    }
+    return surfaces;
+}
+/**
+ * Find exactly one storage plane by semantic coordinates. Throws when the
+ * selector matches nothing or more than one plane.
+ */
+export function findStorageSurface(surfaces, selector) {
+    if (!selector.filesTable && !selector.filesType && !selector.schemaName) {
+        throw new Error('STORAGE_SURFACE_SELECTOR_EMPTY: provide filesTable, filesType, and/or schemaName');
+    }
+    const matches = surfaces.filter((surface) => (selector.filesTable === undefined || surface.filesTable.tableName === selector.filesTable) &&
+        (selector.schemaName === undefined || surface.filesTable.schemaName === selector.schemaName) &&
+        (selector.filesType === undefined || surface.filesType === selector.filesType));
+    if (matches.length === 0) {
+        throw new Error(`STORAGE_SURFACE_NOT_FOUND: no storage plane matches ${JSON.stringify(selector)}; ` +
+            `known planes: ${surfaces.map((s) => `${s.filesTable.schemaName}.${s.filesTable.tableName}`).join(', ') || '(none)'}`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`STORAGE_SURFACE_AMBIGUOUS: ${matches.length} storage planes match ${JSON.stringify(selector)}: ` +
+            matches.map((s) => `${s.filesTable.schemaName}.${s.filesTable.tableName}`).join(', '));
+    }
+    return matches[0];
+}
+function tableRef(table) {
+    return { name: table.name, tableName: table.tableName, schemaName: table.schemaName };
+}

package/esm/storage/transport.js

@@ -0,0 +1,19 @@
+/**
+ * Ports the storage orchestration depends on.
+ *
+ * Byte-level concerns — hashing a file, PUTting it to a presigned URL — are
+ * injected as an adapter rather than imported, so this package stays a
+ * GraphQL discovery/document library with no upload or S3 dependency.
+ * `@constructive-io/upload-client` ships an adapter satisfying
+ * `StorageTransport`; any other implementation works equally well.
+ */
+export class StorageError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = 'StorageError';
+        this.code = code;
+        this.cause = cause;
+    }
+}

package/esm/storage/types.js

@@ -0,0 +1,9 @@
+/**
+ * Dynamic storage-surface types.
+ *
+ * These mirror the `_meta` storage payload emitted by graphile-meta, which in
+ * turn derives from the same registry facts (files→buckets FK pairing,
+ * inflection) the presigned-url plugin emits the schema from. A client that
+ * consumes these never guesses a GraphQL name.
+ */
+export {};

package/esm/storage/upload.js

@@ -0,0 +1,75 @@
+/**
+ * Upload orchestration for one already-resolved storage plane:
+ * hash → dynamic upload mutation → presigned PUT.
+ *
+ * Standalone on purpose — callers that resolved a surface themselves can use
+ * this without the client wrapper, and the byte-level work is an injected
+ * `StorageTransport`.
+ */
+import { buildUploadDocument } from './document';
+import { StorageError } from './transport';
+export async function uploadToSurface(surface, options, context) {
+    const { execute, transport } = context;
+    const { file, bucketKey, key, isPublic, ownerId, signal } = options;
+    if (!file) {
+        throw new StorageError('INVALID_FILE', 'No file provided');
+    }
+    if (file.size <= 0) {
+        throw new StorageError('INVALID_FILE', 'File is empty');
+    }
+    if (surface.upload.requiresOwnerId && !ownerId) {
+        throw new StorageError('OWNER_REQUIRED', `Storage plane ${surface.filesType} is entity-keyed and requires ownerId`);
+    }
+    checkAborted(signal);
+    const contentHash = await transport.hashFile(file);
+    checkAborted(signal);
+    const contentType = file.type || 'application/octet-stream';
+    const input = {
+        contentHash,
+        contentType,
+        size: file.size,
+        filename: file.name || undefined,
+    };
+    if (bucketKey !== undefined)
+        input.bucketKey = bucketKey;
+    if (key !== undefined)
+        input.key = key;
+    if (isPublic !== undefined)
+        input.isPublic = isPublic;
+    if (ownerId !== undefined)
+        input.ownerId = ownerId;
+    let data;
+    try {
+        data = await execute(buildUploadDocument(surface), { input });
+    }
+    catch (err) {
+        throw new StorageError('UPLOAD_MUTATION_FAILED', `${surface.upload.mutation} mutation failed: ${err instanceof Error ? err.message : String(err)}`, err);
+    }
+    const payload = data?.[surface.upload.mutation];
+    if (!payload) {
+        throw new StorageError('UPLOAD_MUTATION_FAILED', `No data returned from ${surface.upload.mutation}`);
+    }
+    if (payload.deduplicated) {
+        return toResult(payload);
+    }
+    if (!payload.uploadUrl) {
+        throw new StorageError('UPLOAD_MUTATION_FAILED', 'Server returned deduplicated=false but no uploadUrl');
+    }
+    checkAborted(signal);
+    await transport.putObject(payload.uploadUrl, await file.arrayBuffer(), contentType, signal);
+    return toResult(payload);
+}
+function toResult(payload) {
+    return {
+        fileId: payload.fileId,
+        key: payload.key,
+        deduplicated: payload.deduplicated,
+        expiresAt: payload.expiresAt ?? null,
+        previousVersionId: payload.previousVersionId ?? null,
+    };
+}
+function checkAborted(signal) {
+    if (signal?.aborted) {
+        throw new StorageError('ABORTED', 'Upload was cancelled');
+    }
+}

package/index.d.ts

@@ -20,4 +20,5 @@ export { validateMetaObject, type ValidationResult } from './meta-object/validat
 export * from './generators';
 export * from './client';
 export * from './introspect';
+export * from './storage';
 export { parseSmartTags, stripSmartComments } from './utils';

package/index.js

@@ -73,6 +73,8 @@ __exportStar(require("./generators"), exports);
 __exportStar(require("./client"), exports);
 // Introspection utilities (infer-tables, transform, transform-schema, schema-query)
 __exportStar(require("./introspect"), exports);
+// Dynamic storage client (discover planes from _meta, build upload documents)
+__exportStar(require("./storage"), exports);
 // Utility functions
 var utils_1 = require("./utils");
 Object.defineProperty(exports, "parseSmartTags", { enumerable: true, get: function () { return utils_1.parseSmartTags; } });

package/meta-object/convert.d.ts

@@ -1,3 +1,4 @@
+import type { StorageUploadSurface } from '../storage/types';
 import type { MetaFieldType } from '../types';
 interface MetaSchemaField {
     name: string;
@@ -20,6 +21,14 @@ interface MetaSchemaBelongsTo {
 interface MetaSchemaRelations {
     belongsTo: MetaSchemaBelongsTo[];
 }
+interface MetaSchemaStorage {
+    isFilesTable: boolean;
+    isBucketsTable: boolean;
+    filesType: string;
+    bucketsType: string;
+    downloadUrlField: string | null;
+    upload: StorageUploadSurface;
+}
 interface MetaSchemaTable {
     name: string;
     fields: MetaSchemaField[];
@@ -27,6 +36,7 @@ interface MetaSchemaTable {
     uniqueConstraints: MetaSchemaConstraint[];
     foreignKeyConstraints: MetaSchemaForeignConstraint[];
     relations: MetaSchemaRelations;
+    storage?: MetaSchemaStorage | null;
 }
 interface MetaSchemaInput {
     _meta: {
@@ -54,6 +64,7 @@ interface ConvertedTable {
     primaryConstraints: ConvertedConstraint[];
     uniqueConstraints: ConvertedConstraint[];
     foreignConstraints: ConvertedForeignConstraint[];
+    storage?: MetaSchemaStorage;
 }
 interface ConvertedMetaObject {
     tables: ConvertedTable[];

package/meta-object/convert.js

@@ -16,6 +16,7 @@ function convertFromMetaSchema(metaSchema) {
             primaryConstraints: pickArrayConstraint(table.primaryKeyConstraints),
             uniqueConstraints: pickArrayConstraint(table.uniqueConstraints),
             foreignConstraints: pickForeignConstraint(table.foreignKeyConstraints, table.relations),
+            ...(table.storage ? { storage: table.storage } : {}),
         });
     }
     return result;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@constructive-io/graphql-query",
-  "version": "4.14.1",
+  "version": "4.15.0",
   "description": "Constructive GraphQL Query",
   "author": "Constructive <developers@constructive.io>",
   "main": "index.js",
@@ -38,7 +38,7 @@
     "grafast": "1.1.2",
     "graphile-build-pg": "5.1.3",
     "graphile-config": "1.1.0",
-    "graphile-settings": "^6.18.1",
+    "graphile-settings": "^6.18.2",
     "graphql": "16.13.0",
     "inflection": "^3.0.0",
     "inflekt": "^0.8.1",
@@ -55,5 +55,5 @@
   "devDependencies": {
     "makage": "^0.3.0"
   },
-  "gitHead": "8d77dfe57bb328cbdfe10732b10ca24865adf9c0"
+  "gitHead": "d10fe91ede80a4c2dfe2c1c6dcf6fe7193784eba"
 }

package/storage/client.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Runtime dynamic storage client — a thin composition of the three modular
+ * pieces: `_meta` discovery, document building, and upload orchestration.
+ *
+ * The caller never names a mutation, input type, or bucket query field.
+ */
+import type { GraphQLExecutor, StorageTransport } from './transport';
+import type { StorageSurface, StorageSurfaceSelector } from './types';
+import type { StorageUploadOptions, StorageUploadResult } from './upload';
+export interface StorageClientOptions {
+    /** GraphQL executor — the only integration point with your GraphQL client */
+    execute: GraphQLExecutor;
+    /**
+     * Byte-level adapter (hash + presigned PUT). Required for `upload()`;
+     * omit it when you only need discovery or document building.
+     */
+    transport?: StorageTransport;
+}
+export interface StorageClient {
+    /** Discover every storage plane from `_meta` (cached after the first call) */
+    discover(): Promise<StorageSurface[]>;
+    /** Resolve exactly one storage plane by semantic coordinates */
+    surface(selector: StorageSurfaceSelector): Promise<StorageSurface>;
+    /** Upload a file to a plane: hash → dynamic upload mutation → presigned PUT */
+    upload(selector: StorageSurfaceSelector, options: StorageUploadOptions): Promise<StorageUploadResult>;
+}
+export declare function createStorageClient(options: StorageClientOptions): StorageClient;

package/storage/client.js

@@ -0,0 +1,33 @@
+"use strict";
+/**
+ * Runtime dynamic storage client — a thin composition of the three modular
+ * pieces: `_meta` discovery, document building, and upload orchestration.
+ *
+ * The caller never names a mutation, input type, or bucket query field.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createStorageClient = createStorageClient;
+const meta_1 = require("./meta");
+const upload_1 = require("./upload");
+function createStorageClient(options) {
+    const { execute, transport } = options;
+    let cachedSurfaces = null;
+    async function discover() {
+        if (cachedSurfaces)
+            return cachedSurfaces;
+        const result = (await execute(meta_1.STORAGE_META_QUERY, {}));
+        cachedSurfaces = (0, meta_1.resolveStorageSurfaces)(result);
+        return cachedSurfaces;
+    }
+    async function surface(selector) {
+        return (0, meta_1.findStorageSurface)(await discover(), selector);
+    }
+    async function upload(selector, uploadOptions) {
+        if (!transport) {
+            throw new Error('STORAGE_TRANSPORT_MISSING: createStorageClient({ transport }) is required to upload; ' +
+                'pass the adapter from @constructive-io/upload-client or your own StorageTransport');
+        }
+        return (0, upload_1.uploadToSurface)(await surface(selector), uploadOptions, { execute, transport });
+    }
+    return { discover, surface, upload };
+}

package/storage/document.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Dynamic GraphQL document construction for storage surfaces.
+ *
+ * Every name in the emitted document comes from the plane's `_meta`-reported
+ * surface — nothing here assembles or guesses a GraphQL name.
+ */
+import type { StorageSurface } from './types';
+/**
+ * Build the single-file upload mutation document for a storage plane:
+ *
+ *   mutation UploadAppFileMutation($input: UploadAppFileInput!) {
+ *     uploadAppFile(input: $input) {
+ *       uploadUrl fileId key deduplicated expiresAt previousVersionId
+ *     }
+ *   }
+ */
+export declare function buildUploadDocument(surface: StorageSurface): string;
+/**
+ * Build the download-URL query document for a file row on a storage plane,
+ * looked up through the files type's single-row query field reported by
+ * `_meta` (`query.one`, e.g. `appFile`), selecting the plane's computed
+ * download field.
+ */
+export declare function buildDownloadUrlDocument(surface: StorageSurface): string;

package/storage/document.js

@@ -0,0 +1,135 @@
+"use strict";
+/**
+ * Dynamic GraphQL document construction for storage surfaces.
+ *
+ * Every name in the emitted document comes from the plane's `_meta`-reported
+ * surface — nothing here assembles or guesses a GraphQL name.
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.buildUploadDocument = buildUploadDocument;
+exports.buildDownloadUrlDocument = buildDownloadUrlDocument;
+const t = __importStar(require("gql-ast"));
+const graphql_1 = require("graphql");
+const UPLOAD_PAYLOAD_FIELDS = [
+    'uploadUrl',
+    'fileId',
+    'key',
+    'deduplicated',
+    'expiresAt',
+    'previousVersionId',
+];
+/**
+ * Build the single-file upload mutation document for a storage plane:
+ *
+ *   mutation UploadAppFileMutation($input: UploadAppFileInput!) {
+ *     uploadAppFile(input: $input) {
+ *       uploadUrl fileId key deduplicated expiresAt previousVersionId
+ *     }
+ *   }
+ */
+function buildUploadDocument(surface) {
+    const { mutation, inputType } = surface.upload;
+    const ast = t.document({
+        definitions: [
+            t.operationDefinition({
+                operation: graphql_1.OperationTypeNode.MUTATION,
+                name: `${capitalize(mutation)}Mutation`,
+                variableDefinitions: [
+                    t.variableDefinition({
+                        variable: t.variable({ name: 'input' }),
+                        type: t.nonNullType({ type: t.namedType({ type: inputType }) }),
+                    }),
+                ],
+                selectionSet: t.selectionSet({
+                    selections: [
+                        t.field({
+                            name: mutation,
+                            args: [t.argument({ name: 'input', value: t.variable({ name: 'input' }) })],
+                            selectionSet: t.selectionSet({
+                                selections: UPLOAD_PAYLOAD_FIELDS.map((name) => t.field({ name })),
+                            }),
+                        }),
+                    ],
+                }),
+            }),
+        ],
+    });
+    return (0, graphql_1.print)(ast);
+}
+/**
+ * Build the download-URL query document for a file row on a storage plane,
+ * looked up through the files type's single-row query field reported by
+ * `_meta` (`query.one`, e.g. `appFile`), selecting the plane's computed
+ * download field.
+ */
+function buildDownloadUrlDocument(surface) {
+    if (!surface.downloadUrlField) {
+        throw new Error(`STORAGE_SURFACE_NO_DOWNLOAD_FIELD: plane ${surface.filesType} reports no download-URL field`);
+    }
+    const nodeField = surface.filesNodeField;
+    if (!nodeField) {
+        throw new Error(`STORAGE_SURFACE_NO_NODE_FIELD: plane ${surface.filesType} reports no single-row query field`);
+    }
+    const ast = t.document({
+        definitions: [
+            t.operationDefinition({
+                operation: graphql_1.OperationTypeNode.QUERY,
+                name: `${surface.filesType}DownloadUrlQuery`,
+                variableDefinitions: [
+                    t.variableDefinition({
+                        variable: t.variable({ name: 'id' }),
+                        type: t.nonNullType({ type: t.namedType({ type: 'UUID' }) }),
+                    }),
+                ],
+                selectionSet: t.selectionSet({
+                    selections: [
+                        t.field({
+                            name: nodeField,
+                            args: [t.argument({ name: 'id', value: t.variable({ name: 'id' }) })],
+                            selectionSet: t.selectionSet({
+                                selections: [t.field({ name: 'id' }), t.field({ name: surface.downloadUrlField })],
+                            }),
+                        }),
+                    ],
+                }),
+            }),
+        ],
+    });
+    return (0, graphql_1.print)(ast);
+}
+function capitalize(value) {
+    return value.charAt(0).toUpperCase() + value.slice(1);
+}

package/storage/index.d.ts

@@ -0,0 +1,10 @@
+export type { StorageClient, StorageClientOptions } from './client';
+export { createStorageClient } from './client';
+export { buildDownloadUrlDocument, buildUploadDocument } from './document';
+export type { StorageMetaResult } from './meta';
+export { findStorageSurface, resolveStorageSurfaces, STORAGE_META_QUERY } from './meta';
+export type { GraphQLExecutor, StorageErrorCode, StorageFile, StorageTransport, } from './transport';
+export { StorageError } from './transport';
+export type { StorageSurface, StorageSurfaceSelector, StorageTableRef, StorageUploadSurface, } from './types';
+export type { StorageUploadOptions, StorageUploadResult, UploadToSurfaceContext, } from './upload';
+export { uploadToSurface } from './upload';

package/storage/index.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadToSurface = exports.StorageError = exports.STORAGE_META_QUERY = exports.resolveStorageSurfaces = exports.findStorageSurface = exports.buildUploadDocument = exports.buildDownloadUrlDocument = exports.createStorageClient = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "createStorageClient", { enumerable: true, get: function () { return client_1.createStorageClient; } });
+var document_1 = require("./document");
+Object.defineProperty(exports, "buildDownloadUrlDocument", { enumerable: true, get: function () { return document_1.buildDownloadUrlDocument; } });
+Object.defineProperty(exports, "buildUploadDocument", { enumerable: true, get: function () { return document_1.buildUploadDocument; } });
+var meta_1 = require("./meta");
+Object.defineProperty(exports, "findStorageSurface", { enumerable: true, get: function () { return meta_1.findStorageSurface; } });
+Object.defineProperty(exports, "resolveStorageSurfaces", { enumerable: true, get: function () { return meta_1.resolveStorageSurfaces; } });
+Object.defineProperty(exports, "STORAGE_META_QUERY", { enumerable: true, get: function () { return meta_1.STORAGE_META_QUERY; } });
+var transport_1 = require("./transport");
+Object.defineProperty(exports, "StorageError", { enumerable: true, get: function () { return transport_1.StorageError; } });
+var upload_1 = require("./upload");
+Object.defineProperty(exports, "uploadToSurface", { enumerable: true, get: function () { return upload_1.uploadToSurface; } });

package/storage/meta.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Storage-surface discovery from the `_meta` root query.
+ *
+ * `_meta` is the semantic storage contract: graphile-meta reports each storage
+ * plane's paired tables and upload surface from the registry's own FK facts,
+ * so resolving here can never disagree with the emitted schema.
+ */
+import type { StorageSurface, StorageSurfaceSelector, StorageUploadSurface } from './types';
+/** The `_meta` selection a dynamic storage client needs. */
+export declare const STORAGE_META_QUERY: string;
+interface StorageMetaTable {
+    name: string;
+    tableName: string;
+    schemaName: string;
+    query?: {
+        one: string | null;
+    } | null;
+    storage: {
+        isFilesTable: boolean;
+        isBucketsTable: boolean;
+        filesType: string;
+        bucketsType: string;
+        downloadUrlField: string | null;
+        upload: StorageUploadSurface;
+    } | null;
+}
+export interface StorageMetaResult {
+    _meta: {
+        tables: StorageMetaTable[];
+    };
+}
+/**
+ * Resolve every storage plane from a `_meta` response. Both sides of a plane
+ * (files and buckets tables) report the same surface; this pairs them back up
+ * and fails loudly on any inconsistency rather than returning a partial plane.
+ */
+export declare function resolveStorageSurfaces(result: StorageMetaResult): StorageSurface[];
+/**
+ * Find exactly one storage plane by semantic coordinates. Throws when the
+ * selector matches nothing or more than one plane.
+ */
+export declare function findStorageSurface(surfaces: StorageSurface[], selector: StorageSurfaceSelector): StorageSurface;
+export {};

package/storage/meta.js

@@ -0,0 +1,128 @@
+"use strict";
+/**
+ * Storage-surface discovery from the `_meta` root query.
+ *
+ * `_meta` is the semantic storage contract: graphile-meta reports each storage
+ * plane's paired tables and upload surface from the registry's own FK facts,
+ * so resolving here can never disagree with the emitted schema.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.STORAGE_META_QUERY = void 0;
+exports.resolveStorageSurfaces = resolveStorageSurfaces;
+exports.findStorageSurface = findStorageSurface;
+/** The `_meta` selection a dynamic storage client needs. */
+exports.STORAGE_META_QUERY = `
+query StorageMeta {
+  _meta {
+    tables {
+      name
+      tableName
+      schemaName
+      query {
+        one
+      }
+      storage {
+        isFilesTable
+        isBucketsTable
+        filesType
+        bucketsType
+        downloadUrlField
+        upload {
+          mutation
+          inputType
+          payloadType
+          bulkMutation
+          bulkInputType
+          bulkPayloadType
+          bulkFileInputType
+          bulkFilePayloadType
+          requiresOwnerId
+        }
+      }
+    }
+  }
+}
+`.trim();
+/**
+ * Resolve every storage plane from a `_meta` response. Both sides of a plane
+ * (files and buckets tables) report the same surface; this pairs them back up
+ * and fails loudly on any inconsistency rather than returning a partial plane.
+ */
+function resolveStorageSurfaces(result) {
+    const tables = result?._meta?.tables;
+    if (!Array.isArray(tables)) {
+        throw new Error('STORAGE_META_MALFORMED: _meta.tables missing from response');
+    }
+    const filesByType = new Map();
+    const bucketsByType = new Map();
+    for (const table of tables) {
+        if (!table.storage)
+            continue;
+        const { isFilesTable, isBucketsTable, filesType } = table.storage;
+        if (isFilesTable) {
+            const existing = filesByType.get(filesType);
+            if (existing) {
+                throw new Error(`STORAGE_META_MALFORMED: two files tables (${existing.schemaName}.${existing.tableName}, ` +
+                    `${table.schemaName}.${table.tableName}) report the same plane ${filesType}`);
+            }
+            filesByType.set(filesType, table);
+        }
+        else if (isBucketsTable) {
+            const existing = bucketsByType.get(filesType);
+            if (existing) {
+                throw new Error(`STORAGE_META_MALFORMED: two buckets tables (${existing.schemaName}.${existing.tableName}, ` +
+                    `${table.schemaName}.${table.tableName}) report the same plane ${filesType}`);
+            }
+            bucketsByType.set(filesType, table);
+        }
+        else {
+            throw new Error(`STORAGE_META_MALFORMED: table ${table.schemaName}.${table.tableName} carries storage ` +
+                `metadata but is neither a files nor a buckets table`);
+        }
+    }
+    for (const [filesType, bucketsTable] of bucketsByType) {
+        if (!filesByType.has(filesType)) {
+            throw new Error(`STORAGE_META_MALFORMED: buckets table ${bucketsTable.schemaName}.${bucketsTable.tableName} ` +
+                `reports plane ${filesType} but no files table does`);
+        }
+    }
+    const surfaces = [];
+    for (const [filesType, filesTable] of filesByType) {
+        const storage = filesTable.storage;
+        const bucketsTable = bucketsByType.get(filesType) ?? null;
+        surfaces.push({
+            filesType,
+            bucketsType: storage.bucketsType,
+            filesTable: tableRef(filesTable),
+            bucketsTable: bucketsTable ? tableRef(bucketsTable) : null,
+            filesNodeField: filesTable.query?.one ?? null,
+            downloadUrlField: storage.downloadUrlField,
+            upload: storage.upload,
+        });
+    }
+    return surfaces;
+}
+/**
+ * Find exactly one storage plane by semantic coordinates. Throws when the
+ * selector matches nothing or more than one plane.
+ */
+function findStorageSurface(surfaces, selector) {
+    if (!selector.filesTable && !selector.filesType && !selector.schemaName) {
+        throw new Error('STORAGE_SURFACE_SELECTOR_EMPTY: provide filesTable, filesType, and/or schemaName');
+    }
+    const matches = surfaces.filter((surface) => (selector.filesTable === undefined || surface.filesTable.tableName === selector.filesTable) &&
+        (selector.schemaName === undefined || surface.filesTable.schemaName === selector.schemaName) &&
+        (selector.filesType === undefined || surface.filesType === selector.filesType));
+    if (matches.length === 0) {
+        throw new Error(`STORAGE_SURFACE_NOT_FOUND: no storage plane matches ${JSON.stringify(selector)}; ` +
+            `known planes: ${surfaces.map((s) => `${s.filesTable.schemaName}.${s.filesTable.tableName}`).join(', ') || '(none)'}`);
+    }
+    if (matches.length > 1) {
+        throw new Error(`STORAGE_SURFACE_AMBIGUOUS: ${matches.length} storage planes match ${JSON.stringify(selector)}: ` +
+            matches.map((s) => `${s.filesTable.schemaName}.${s.filesTable.tableName}`).join(', '));
+    }
+    return matches[0];
+}
+function tableRef(table) {
+    return { name: table.name, tableName: table.tableName, schemaName: table.schemaName };
+}

package/storage/transport.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Ports the storage orchestration depends on.
+ *
+ * Byte-level concerns — hashing a file, PUTting it to a presigned URL — are
+ * injected as an adapter rather than imported, so this package stays a
+ * GraphQL discovery/document library with no upload or S3 dependency.
+ * `@constructive-io/upload-client` ships an adapter satisfying
+ * `StorageTransport`; any other implementation works equally well.
+ */
+/**
+ * Minimal file interface for hashing and uploading.
+ * Compatible with browser `File`, Node.js `Blob`, and custom implementations.
+ */
+export interface StorageFile {
+    readonly name: string;
+    readonly size: number;
+    readonly type: string;
+    arrayBuffer(): Promise<ArrayBuffer>;
+}
+/** Byte-level adapter: content hashing and presigned PUT. */
+export interface StorageTransport {
+    /** SHA-256 the file contents, hex-encoded */
+    hashFile(file: StorageFile): Promise<string>;
+    /** PUT the bytes to a presigned URL */
+    putObject(url: string, body: ArrayBuffer, contentType: string, signal?: AbortSignal): Promise<void>;
+}
+/**
+ * Executes a GraphQL operation and returns its `data`.
+ * The only integration point with a GraphQL client.
+ */
+export type GraphQLExecutor = (query: string, variables: Record<string, unknown>) => Promise<Record<string, unknown>>;
+export type StorageErrorCode = 'INVALID_FILE' | 'OWNER_REQUIRED' | 'HASH_FAILED' | 'UPLOAD_MUTATION_FAILED' | 'PUT_UPLOAD_FAILED' | 'ABORTED';
+export declare class StorageError extends Error {
+    readonly code: StorageErrorCode;
+    readonly cause?: unknown;
+    constructor(code: StorageErrorCode, message: string, cause?: unknown);
+}

package/storage/transport.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Ports the storage orchestration depends on.
+ *
+ * Byte-level concerns — hashing a file, PUTting it to a presigned URL — are
+ * injected as an adapter rather than imported, so this package stays a
+ * GraphQL discovery/document library with no upload or S3 dependency.
+ * `@constructive-io/upload-client` ships an adapter satisfying
+ * `StorageTransport`; any other implementation works equally well.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageError = void 0;
+class StorageError extends Error {
+    code;
+    cause;
+    constructor(code, message, cause) {
+        super(message);
+        this.name = 'StorageError';
+        this.code = code;
+        this.cause = cause;
+    }
+}
+exports.StorageError = StorageError;

package/storage/types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Dynamic storage-surface types.
+ *
+ * These mirror the `_meta` storage payload emitted by graphile-meta, which in
+ * turn derives from the same registry facts (files→buckets FK pairing,
+ * inflection) the presigned-url plugin emits the schema from. A client that
+ * consumes these never guesses a GraphQL name.
+ */
+/** The GraphQL upload surface of a storage plane, as reported by `_meta`. */
+export interface StorageUploadSurface {
+    /** Root mutation field for single-file upload (e.g. `uploadAppFile`) */
+    mutation: string;
+    /** Input type of the single upload mutation (e.g. `UploadAppFileInput`) */
+    inputType: string;
+    /** Payload type of the single upload mutation */
+    payloadType: string;
+    /** Root mutation field for bulk upload */
+    bulkMutation: string;
+    /** Input type of the bulk upload mutation */
+    bulkInputType: string;
+    /** Payload type of the bulk upload mutation */
+    bulkPayloadType: string;
+    /** Per-file input type inside the bulk input */
+    bulkFileInputType: string;
+    /** Per-file payload type inside the bulk payload */
+    bulkFilePayloadType: string;
+    /** Whether the upload input requires `ownerId` (entity-keyed plane) */
+    requiresOwnerId: boolean;
+}
+/** The pg identity of a `_meta` table entry backing a storage plane side. */
+export interface StorageTableRef {
+    /** Final GraphQL type name */
+    name: string;
+    /** PostgreSQL table name */
+    tableName: string;
+    /** PostgreSQL schema name */
+    schemaName: string;
+}
+/** One storage plane: a paired files/buckets table and its GraphQL surface. */
+export interface StorageSurface {
+    /** GraphQL type name of the plane's files table */
+    filesType: string;
+    /** GraphQL type name of the plane's buckets table */
+    bucketsType: string;
+    /** The files table's `_meta` identity */
+    filesTable: StorageTableRef;
+    /** The buckets table's `_meta` identity (null when the buckets table is not exposed) */
+    bucketsTable: StorageTableRef | null;
+    /** Root query field for a single files row by primary key (from `_meta` query.one) */
+    filesNodeField: string | null;
+    /** Computed download-URL field on the files type */
+    downloadUrlField: string | null;
+    /** The plane's GraphQL upload surface */
+    upload: StorageUploadSurface;
+}
+/**
+ * Selects one storage plane by semantic coordinates. All provided fields must
+ * match exactly; the lookup throws when nothing (or more than one plane)
+ * matches.
+ */
+export interface StorageSurfaceSelector {
+    /** PostgreSQL table name of the files table (e.g. `files`, `app_files`) */
+    filesTable?: string;
+    /** PostgreSQL schema name of the files table */
+    schemaName?: string;
+    /** GraphQL type name of the files table (e.g. `AppFile`) */
+    filesType?: string;
+}

package/storage/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Dynamic storage-surface types.
+ *
+ * These mirror the `_meta` storage payload emitted by graphile-meta, which in
+ * turn derives from the same registry facts (files→buckets FK pairing,
+ * inflection) the presigned-url plugin emits the schema from. A client that
+ * consumes these never guesses a GraphQL name.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });

package/storage/upload.d.ts

@@ -0,0 +1,41 @@
+/**
+ * Upload orchestration for one already-resolved storage plane:
+ * hash → dynamic upload mutation → presigned PUT.
+ *
+ * Standalone on purpose — callers that resolved a surface themselves can use
+ * this without the client wrapper, and the byte-level work is an injected
+ * `StorageTransport`.
+ */
+import type { GraphQLExecutor, StorageFile, StorageTransport } from './transport';
+import type { StorageSurface } from './types';
+export interface StorageUploadOptions {
+    /** The file to upload (browser File object or compatible) */
+    file: StorageFile;
+    /** Bucket key within the plane (omit to use the plane's default bucket) */
+    bucketKey?: string;
+    /** Custom object key (enables versioning of the same key) */
+    key?: string;
+    /** Whether the file should be publicly readable */
+    isPublic?: boolean;
+    /** Owner identity — required when the plane is entity-keyed */
+    ownerId?: string;
+    /** AbortSignal for cancellation */
+    signal?: AbortSignal;
+}
+export interface StorageUploadResult {
+    /** The file ID (UUID) */
+    fileId: string;
+    /** The object key */
+    key: string;
+    /** Whether this file was deduplicated (no bytes uploaded) */
+    deduplicated: boolean;
+    /** Presigned URL expiry time (null if deduplicated) */
+    expiresAt: string | null;
+    /** ID of the previous version (when uploading a new version of a custom-keyed file) */
+    previousVersionId: string | null;
+}
+export interface UploadToSurfaceContext {
+    execute: GraphQLExecutor;
+    transport: StorageTransport;
+}
+export declare function uploadToSurface(surface: StorageSurface, options: StorageUploadOptions, context: UploadToSurfaceContext): Promise<StorageUploadResult>;

package/storage/upload.js

@@ -0,0 +1,78 @@
+"use strict";
+/**
+ * Upload orchestration for one already-resolved storage plane:
+ * hash → dynamic upload mutation → presigned PUT.
+ *
+ * Standalone on purpose — callers that resolved a surface themselves can use
+ * this without the client wrapper, and the byte-level work is an injected
+ * `StorageTransport`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.uploadToSurface = uploadToSurface;
+const document_1 = require("./document");
+const transport_1 = require("./transport");
+async function uploadToSurface(surface, options, context) {
+    const { execute, transport } = context;
+    const { file, bucketKey, key, isPublic, ownerId, signal } = options;
+    if (!file) {
+        throw new transport_1.StorageError('INVALID_FILE', 'No file provided');
+    }
+    if (file.size <= 0) {
+        throw new transport_1.StorageError('INVALID_FILE', 'File is empty');
+    }
+    if (surface.upload.requiresOwnerId && !ownerId) {
+        throw new transport_1.StorageError('OWNER_REQUIRED', `Storage plane ${surface.filesType} is entity-keyed and requires ownerId`);
+    }
+    checkAborted(signal);
+    const contentHash = await transport.hashFile(file);
+    checkAborted(signal);
+    const contentType = file.type || 'application/octet-stream';
+    const input = {
+        contentHash,
+        contentType,
+        size: file.size,
+        filename: file.name || undefined,
+    };
+    if (bucketKey !== undefined)
+        input.bucketKey = bucketKey;
+    if (key !== undefined)
+        input.key = key;
+    if (isPublic !== undefined)
+        input.isPublic = isPublic;
+    if (ownerId !== undefined)
+        input.ownerId = ownerId;
+    let data;
+    try {
+        data = await execute((0, document_1.buildUploadDocument)(surface), { input });
+    }
+    catch (err) {
+        throw new transport_1.StorageError('UPLOAD_MUTATION_FAILED', `${surface.upload.mutation} mutation failed: ${err instanceof Error ? err.message : String(err)}`, err);
+    }
+    const payload = data?.[surface.upload.mutation];
+    if (!payload) {
+        throw new transport_1.StorageError('UPLOAD_MUTATION_FAILED', `No data returned from ${surface.upload.mutation}`);
+    }
+    if (payload.deduplicated) {
+        return toResult(payload);
+    }
+    if (!payload.uploadUrl) {
+        throw new transport_1.StorageError('UPLOAD_MUTATION_FAILED', 'Server returned deduplicated=false but no uploadUrl');
+    }
+    checkAborted(signal);
+    await transport.putObject(payload.uploadUrl, await file.arrayBuffer(), contentType, signal);
+    return toResult(payload);
+}
+function toResult(payload) {
+    return {
+        fileId: payload.fileId,
+        key: payload.key,
+        deduplicated: payload.deduplicated,
+        expiresAt: payload.expiresAt ?? null,
+        previousVersionId: payload.previousVersionId ?? null,
+    };
+}
+function checkAborted(signal) {
+    if (signal?.aborted) {
+        throw new transport_1.StorageError('ABORTED', 'Upload was cancelled');
+    }
+}