graphile-presigned-url-plugin 0.19.2 → 0.20.1

package/README.md

@@ -92,6 +92,21 @@ Common issues and solutions for pgpm, PostgreSQL, and testing.
 * [@pgsql/types](https://www.npmjs.com/package/@pgsql/types): **📝 Type definitions** for PostgreSQL AST nodes in TypeScript.
 * [@pgsql/utils](https://www.npmjs.com/package/@pgsql/utils): **🛠️ AST utilities** for constructing and transforming PostgreSQL syntax trees.
 
+### 📚 Documentation & Skills
+
+* [constructive-skills](https://github.com/constructive-io/constructive-skills): **📖 Platform documentation and AI agent skills** — feature catalog, blueprint reference, SDK guides (i18n, billing, limits, events, uploads, security, entities, search, AI), and deployment guides.
+
+Install skills for AI coding agents:
+
+```bash
+# All platform skills (security, blueprints, codegen, billing, etc.)
+npx skills add constructive-io/constructive-skills
+
+# Individual repo skills (pgpm, testing, CLI, search, etc.)
+npx skills add https://github.com/constructive-io/constructive --skill pgpm
+npx skills add https://github.com/constructive-io/constructive --skill constructive-testing
+```
+
 ## Credits
 
 **🛠 Built by the [Constructive](https://constructive.io) team — creators of modular Postgres tooling for secure, composable backends. If you like our work, contribute on [GitHub](https://github.com/constructive-io).**

package/download-url-field.js

@@ -115,7 +115,7 @@ function createDownloadUrlPlugin(options) {
                                     let downloadUrlExpirySeconds = 3600;
                                     try {
                                         if (withPgClient && pgSettings) {
-                                            const resolved = await withPgClient(null, async (pgClient) => {
+                                            const resolved = await withPgClient(pgSettings, async (pgClient) => {
                                                 const dbResult = await pgClient.query({
                                                     text: `SELECT jwt_private.current_database_id() AS id`,
                                                 });

package/esm/download-url-field.js

@@ -112,7 +112,7 @@ export function createDownloadUrlPlugin(options) {
                                     let downloadUrlExpirySeconds = 3600;
                                     try {
                                         if (withPgClient && pgSettings) {
-                                            const resolved = await withPgClient(null, async (pgClient) => {
+                                            const resolved = await withPgClient(pgSettings, async (pgClient) => {
                                                 const dbResult = await pgClient.query({
                                                     text: `SELECT jwt_private.current_database_id() AS id`,
                                                 });

package/esm/plugin.js

@@ -559,7 +559,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
     // Auto-derive ltree path from custom key directory (only when has_path_shares)
     const derivedPath = isCustomKey && storageConfig.hasPathShares ? derivePathFromKey(s3Key) : null;
     // Create file record
-    const hasOwnerColumn = storageConfig.membershipType !== null;
+    const hasOwnerColumn = storageConfig.scope !== 'app';
     const columns = ['bucket_id', 'key', 'content_hash', 'mime_type', 'size', 'filename', 'is_public'];
     const values = [bucket.id, s3Key, contentHash, contentType, size, filename || null, bucket.is_public];
     if (hasOwnerColumn) {

package/esm/storage-module-cache.d.ts

@@ -3,7 +3,7 @@ import type { StorageModuleConfig, BucketConfig } from './types';
  * Resolve the app-level storage module config for a database, using the LRU cache.
  *
  * This is the default path when no ownerId is provided. It returns the
- * storage module with membership_type IS NULL (app-level / database-wide).
+ * storage module with scope = 'app' (app-level / database-wide).
  *
  * @param pgClient - A pg client from the Graphile context (withPgClient or pgClient)
  * @param databaseId - The metaschema database UUID

package/esm/storage-module-cache.js

@@ -31,14 +31,14 @@ const storageModuleCache = new LRUCache({
  * SQL query to resolve the app-level storage module config for a database.
  *
  * Joins storage_module → table → schema to get fully-qualified table names.
- * Filters to app-level (membership_type IS NULL) by default.
+ * Filters to app-level (scope = 'app') by default.
  *
- * Requires the multi-scope schema (membership_type column on storage_module).
+ * Requires the multi-scope schema (scope column on storage_module).
  */
 const APP_STORAGE_MODULE_QUERY = `
   SELECT
     sm.id,
-    sm.membership_type,
+    sm.scope,
     sm.entity_table_id,
     bs.schema_name AS buckets_schema,
     bt.name AS buckets_table,
@@ -64,7 +64,7 @@ const APP_STORAGE_MODULE_QUERY = `
   JOIN metaschema_public.table ft ON ft.id = sm.files_table_id
   JOIN metaschema_public.schema fs ON fs.id = ft.schema_id
   WHERE sm.database_id = $1
-    AND sm.membership_type IS NULL
+    AND sm.scope = 'app'
   LIMIT 1
 `;
 /**
@@ -76,7 +76,7 @@ const APP_STORAGE_MODULE_QUERY = `
 const ALL_STORAGE_MODULES_QUERY = `
   SELECT
     sm.id,
-    sm.membership_type,
+    sm.scope,
     sm.entity_table_id,
     bs.schema_name AS buckets_schema,
     bt.name AS buckets_table,
@@ -117,7 +117,7 @@ function buildConfig(row) {
         schemaName: row.buckets_schema,
         bucketsTableName: row.buckets_table,
         filesTableName: row.files_table,
-        membershipType: row.membership_type,
+        scope: row.scope,
         entityTableId: row.entity_table_id,
         entityQualifiedName: row.entity_schema && row.entity_table
             ? QuoteUtils.quoteQualifiedIdentifier(row.entity_schema, row.entity_table)
@@ -140,7 +140,7 @@ function buildConfig(row) {
  * Resolve the app-level storage module config for a database, using the LRU cache.
  *
  * This is the default path when no ownerId is provided. It returns the
- * storage module with membership_type IS NULL (app-level / database-wide).
+ * storage module with scope = 'app' (app-level / database-wide).
  *
  * @param pgClient - A pg client from the Graphile context (withPgClient or pgClient)
  * @param databaseId - The metaschema database UUID
@@ -201,11 +201,9 @@ export async function getStorageModuleConfigForOwner(pgClient, databaseId, owner
         log.debug(`Loading all storage modules for database ${databaseId} to resolve ownerId ${ownerId}`);
         const result = await pgClient.query({ text: ALL_STORAGE_MODULES_QUERY, values: [databaseId] });
         allConfigs = result.rows.map(buildConfig);
-        // Cache each individual config by its membership type
+        // Cache each individual config by its scope
         for (const config of allConfigs) {
-            const key = config.membershipType === null
-                ? `storage:${databaseId}:app`
-                : `storage:${databaseId}:mt:${config.membershipType}`;
+            const key = `storage:${databaseId}:scope:${config.scope}`;
             storageModuleCache.set(key, config);
         }
     }
@@ -220,7 +218,7 @@ export async function getStorageModuleConfigForOwner(pgClient, databaseId, owner
             // Found the matching module — cache the ownerId→module mapping
             storageModuleCache.set(ownerCacheKey, mod);
             log.debug(`Resolved ownerId ${ownerId} to storage module ${mod.id} ` +
-                `(membershipType=${mod.membershipType}, table=${mod.bucketsQualifiedName})`);
+                `(scope=${mod.scope}, table=${mod.bucketsQualifiedName})`);
             return mod;
         }
     }
@@ -272,16 +270,16 @@ export async function loadAllStorageModules(pgClient, databaseId) {
     log.debug(`Loading all storage modules for database ${databaseId}`);
     const result = await pgClient.query({ text: ALL_STORAGE_MODULES_QUERY, values: [databaseId] });
     const configs = result.rows.map(buildConfig);
-    // Cache each individual config by its membership type
+    // Cache each individual config by its scope
     for (const config of configs) {
-        const key = config.membershipType === null
-            ? `storage:${databaseId}:app`
-            : `storage:${databaseId}:mt:${config.membershipType}`;
+        const key = `storage:${databaseId}:scope:${config.scope}`;
         storageModuleCache.set(key, config);
     }
-    // Store the full list under a sentinel key
-    const sentinel = { ...configs[0] || {}, _allConfigs: configs };
-    storageModuleCache.set(cacheKey, sentinel);
+    // Store the full list under a sentinel key (only if non-empty to avoid caching failed lookups)
+    if (configs.length > 0) {
+        const sentinel = { ...configs[0], _allConfigs: configs };
+        storageModuleCache.set(cacheKey, sentinel);
+    }
     return configs;
 }
 /**
@@ -344,14 +342,15 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
     log.debug(`Bucket cache miss for ${databaseId}:${bucketKey}${ownerId ? ` (owner=${ownerId})` : ''}, querying DB...`);
     // Entity-scoped buckets use (owner_id, key) composite lookup;
     // app-level buckets just use key.
-    const hasOwner = ownerId && storageConfig.membershipType !== null;
+    const isEntityScoped = storageConfig.scope !== 'app';
+    const hasOwner = ownerId && isEntityScoped;
     const result = await pgClient.query({
         text: hasOwner
             ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size, allow_custom_keys
          FROM ${storageConfig.bucketsQualifiedName}
          WHERE key = $1 AND owner_id = $2
          LIMIT 1`
-            : `SELECT id, key, type, is_public, ${storageConfig.membershipType !== null ? 'owner_id,' : ''} allowed_mime_types, max_file_size, allow_custom_keys
+            : `SELECT id, key, type, is_public, ${isEntityScoped ? 'owner_id,' : ''} allowed_mime_types, max_file_size, allow_custom_keys
          FROM ${storageConfig.bucketsQualifiedName}
          WHERE key = $1
          LIMIT 1`,
@@ -372,7 +371,7 @@ export async function getBucketConfig(pgClient, storageConfig, databaseId, bucke
         allow_custom_keys: row.allow_custom_keys ?? false,
     };
     bucketCache.set(cacheKey, config);
-    log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.membershipType ?? 'app'})`);
+    log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.scope})`);
     return config;
 }
 // --- S3 bucket existence cache ---

package/esm/types.d.ts

@@ -28,8 +28,8 @@ export interface StorageModuleConfig {
     bucketsTableName: string;
     /** Files table name */
     filesTableName: string;
-    /** Membership type (NULL for app-level, non-NULL for entity-scoped) */
-    membershipType: number | null;
+    /** Scope name (e.g., 'app', 'org', 'team') */
+    scope: string;
     /** Entity table ID for entity-scoped storage (NULL for app-level) */
     entityTableId: string | null;
     /** Qualified entity table name for ownerId lookups (NULL for app-level) */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "graphile-presigned-url-plugin",
-  "version": "0.19.2",
+  "version": "0.20.1",
   "description": "Presigned URL upload plugin for PostGraphile v5 — requestUploadUrl mutation and downloadUrl computed field",
   "author": "Constructive <developers@constructive.io>",
   "homepage": "https://github.com/constructive-io/constructive",
@@ -42,7 +42,7 @@
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1052.0",
     "@aws-sdk/s3-request-presigner": "^3.1052.0",
-    "@pgpmjs/logger": "^2.11.1",
+    "@pgpmjs/logger": "^2.12.0",
     "@pgsql/quotes": "^17.1.0",
     "lru-cache": "^11.2.7"
   },
@@ -56,9 +56,9 @@
     "postgraphile": "5.0.3"
   },
   "devDependencies": {
-    "@constructive-io/s3-utils": "^2.17.2",
+    "@constructive-io/s3-utils": "^2.18.0",
     "@types/node": "^22.19.11",
     "makage": "^0.3.0"
   },
-  "gitHead": "423992019655cc1e780149ce3f7e6e8c9b1c6e80"
+  "gitHead": "d398ac2288f57fa02713353ce36024a63dd6b9f1"
 }

package/plugin.js

@@ -563,7 +563,7 @@ async function processSingleFile(options, txClient, storageConfig, databaseId, b
     // Auto-derive ltree path from custom key directory (only when has_path_shares)
     const derivedPath = isCustomKey && storageConfig.hasPathShares ? derivePathFromKey(s3Key) : null;
     // Create file record
-    const hasOwnerColumn = storageConfig.membershipType !== null;
+    const hasOwnerColumn = storageConfig.scope !== 'app';
     const columns = ['bucket_id', 'key', 'content_hash', 'mime_type', 'size', 'filename', 'is_public'];
     const values = [bucket.id, s3Key, contentHash, contentType, size, filename || null, bucket.is_public];
     if (hasOwnerColumn) {

package/storage-module-cache.d.ts

@@ -3,7 +3,7 @@ import type { StorageModuleConfig, BucketConfig } from './types';
  * Resolve the app-level storage module config for a database, using the LRU cache.
  *
  * This is the default path when no ownerId is provided. It returns the
- * storage module with membership_type IS NULL (app-level / database-wide).
+ * storage module with scope = 'app' (app-level / database-wide).
  *
  * @param pgClient - A pg client from the Graphile context (withPgClient or pgClient)
  * @param databaseId - The metaschema database UUID

package/storage-module-cache.js

@@ -43,14 +43,14 @@ const storageModuleCache = new lru_cache_1.LRUCache({
  * SQL query to resolve the app-level storage module config for a database.
  *
  * Joins storage_module → table → schema to get fully-qualified table names.
- * Filters to app-level (membership_type IS NULL) by default.
+ * Filters to app-level (scope = 'app') by default.
  *
- * Requires the multi-scope schema (membership_type column on storage_module).
+ * Requires the multi-scope schema (scope column on storage_module).
  */
 const APP_STORAGE_MODULE_QUERY = `
   SELECT
     sm.id,
-    sm.membership_type,
+    sm.scope,
     sm.entity_table_id,
     bs.schema_name AS buckets_schema,
     bt.name AS buckets_table,
@@ -76,7 +76,7 @@ const APP_STORAGE_MODULE_QUERY = `
   JOIN metaschema_public.table ft ON ft.id = sm.files_table_id
   JOIN metaschema_public.schema fs ON fs.id = ft.schema_id
   WHERE sm.database_id = $1
-    AND sm.membership_type IS NULL
+    AND sm.scope = 'app'
   LIMIT 1
 `;
 /**
@@ -88,7 +88,7 @@ const APP_STORAGE_MODULE_QUERY = `
 const ALL_STORAGE_MODULES_QUERY = `
   SELECT
     sm.id,
-    sm.membership_type,
+    sm.scope,
     sm.entity_table_id,
     bs.schema_name AS buckets_schema,
     bt.name AS buckets_table,
@@ -129,7 +129,7 @@ function buildConfig(row) {
         schemaName: row.buckets_schema,
         bucketsTableName: row.buckets_table,
         filesTableName: row.files_table,
-        membershipType: row.membership_type,
+        scope: row.scope,
         entityTableId: row.entity_table_id,
         entityQualifiedName: row.entity_schema && row.entity_table
             ? quotes_1.QuoteUtils.quoteQualifiedIdentifier(row.entity_schema, row.entity_table)
@@ -152,7 +152,7 @@ function buildConfig(row) {
  * Resolve the app-level storage module config for a database, using the LRU cache.
  *
  * This is the default path when no ownerId is provided. It returns the
- * storage module with membership_type IS NULL (app-level / database-wide).
+ * storage module with scope = 'app' (app-level / database-wide).
  *
  * @param pgClient - A pg client from the Graphile context (withPgClient or pgClient)
  * @param databaseId - The metaschema database UUID
@@ -213,11 +213,9 @@ async function getStorageModuleConfigForOwner(pgClient, databaseId, ownerId) {
         log.debug(`Loading all storage modules for database ${databaseId} to resolve ownerId ${ownerId}`);
         const result = await pgClient.query({ text: ALL_STORAGE_MODULES_QUERY, values: [databaseId] });
         allConfigs = result.rows.map(buildConfig);
-        // Cache each individual config by its membership type
+        // Cache each individual config by its scope
         for (const config of allConfigs) {
-            const key = config.membershipType === null
-                ? `storage:${databaseId}:app`
-                : `storage:${databaseId}:mt:${config.membershipType}`;
+            const key = `storage:${databaseId}:scope:${config.scope}`;
             storageModuleCache.set(key, config);
         }
     }
@@ -232,7 +230,7 @@ async function getStorageModuleConfigForOwner(pgClient, databaseId, ownerId) {
             // Found the matching module — cache the ownerId→module mapping
             storageModuleCache.set(ownerCacheKey, mod);
             log.debug(`Resolved ownerId ${ownerId} to storage module ${mod.id} ` +
-                `(membershipType=${mod.membershipType}, table=${mod.bucketsQualifiedName})`);
+                `(scope=${mod.scope}, table=${mod.bucketsQualifiedName})`);
             return mod;
         }
     }
@@ -284,16 +282,16 @@ async function loadAllStorageModules(pgClient, databaseId) {
     log.debug(`Loading all storage modules for database ${databaseId}`);
     const result = await pgClient.query({ text: ALL_STORAGE_MODULES_QUERY, values: [databaseId] });
     const configs = result.rows.map(buildConfig);
-    // Cache each individual config by its membership type
+    // Cache each individual config by its scope
     for (const config of configs) {
-        const key = config.membershipType === null
-            ? `storage:${databaseId}:app`
-            : `storage:${databaseId}:mt:${config.membershipType}`;
+        const key = `storage:${databaseId}:scope:${config.scope}`;
         storageModuleCache.set(key, config);
     }
-    // Store the full list under a sentinel key
-    const sentinel = { ...configs[0] || {}, _allConfigs: configs };
-    storageModuleCache.set(cacheKey, sentinel);
+    // Store the full list under a sentinel key (only if non-empty to avoid caching failed lookups)
+    if (configs.length > 0) {
+        const sentinel = { ...configs[0], _allConfigs: configs };
+        storageModuleCache.set(cacheKey, sentinel);
+    }
     return configs;
 }
 /**
@@ -356,14 +354,15 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey, o
     log.debug(`Bucket cache miss for ${databaseId}:${bucketKey}${ownerId ? ` (owner=${ownerId})` : ''}, querying DB...`);
     // Entity-scoped buckets use (owner_id, key) composite lookup;
     // app-level buckets just use key.
-    const hasOwner = ownerId && storageConfig.membershipType !== null;
+    const isEntityScoped = storageConfig.scope !== 'app';
+    const hasOwner = ownerId && isEntityScoped;
     const result = await pgClient.query({
         text: hasOwner
             ? `SELECT id, key, type, is_public, owner_id, allowed_mime_types, max_file_size, allow_custom_keys
          FROM ${storageConfig.bucketsQualifiedName}
          WHERE key = $1 AND owner_id = $2
          LIMIT 1`
-            : `SELECT id, key, type, is_public, ${storageConfig.membershipType !== null ? 'owner_id,' : ''} allowed_mime_types, max_file_size, allow_custom_keys
+            : `SELECT id, key, type, is_public, ${isEntityScoped ? 'owner_id,' : ''} allowed_mime_types, max_file_size, allow_custom_keys
          FROM ${storageConfig.bucketsQualifiedName}
          WHERE key = $1
          LIMIT 1`,
@@ -384,7 +383,7 @@ async function getBucketConfig(pgClient, storageConfig, databaseId, bucketKey, o
         allow_custom_keys: row.allow_custom_keys ?? false,
     };
     bucketCache.set(cacheKey, config);
-    log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.membershipType ?? 'app'})`);
+    log.debug(`Cached bucket config for ${databaseId}:${bucketKey} (id=${config.id}, scope=${storageConfig.scope})`);
     return config;
 }
 // --- S3 bucket existence cache ---

package/types.d.ts

@@ -28,8 +28,8 @@ export interface StorageModuleConfig {
     bucketsTableName: string;
     /** Files table name */
     filesTableName: string;
-    /** Membership type (NULL for app-level, non-NULL for entity-scoped) */
-    membershipType: number | null;
+    /** Scope name (e.g., 'app', 'org', 'team') */
+    scope: string;
     /** Entity table ID for entity-scoped storage (NULL for app-level) */
     entityTableId: string | null;
     /** Qualified entity table name for ownerId lookups (NULL for app-level) */