@kubun/graphql 0.17.2 → 0.18.0

package/lib/context.d.ts

@@ -1,6 +1,7 @@
 import { DocumentID } from '@kubun/id';
 import type { AggregateHaving, AggregateSpec, AggregateValues, DocumentData, DocumentFilter, DocumentNode, DocumentOrderBy, GroupedAggregateOrderTerm, GroupedAggregateValue } from '@kubun/protocol';
-import type { SearchDocumentResult, SearchDocumentsParams, StoredAccessDefaultRow, ViewerReadAccess } from '@kubun/store-graph';
+import type { SignedRecord } from '@kubun/records';
+import type { CatalogDefinition, CatalogLevel, CatalogRuleConflict, CatalogRuleResolutionInput, DocumentHold, DocumentScopeView, SearchDocumentResult, SearchDocumentsParams, StoredAccessDefaultRow, ViewerReadAccess } from '@kubun/store-graph';
 import type { Tracer } from '@sozai/otel';
 import type { GraphQLResolveInfo } from 'graphql';
 import type { Connection, Edge } from './relay.js';
@@ -34,7 +35,10 @@ export type ReadContextDB = {
         filter?: DocumentFilter;
         orderBy?: DocumentOrderBy;
         owner?: string;
-        catalogID?: string;
+        catalogRef?: {
+            owner: string;
+            id: string;
+        };
         first?: number | null;
         last?: number | null;
         before?: string | null;
@@ -54,7 +58,10 @@ export type ReadContextDB = {
         modelIDs: Array<string>;
         filter?: DocumentFilter;
         owner?: string;
-        catalogID?: string;
+        catalogRef?: {
+            owner: string;
+            id: string;
+        };
         count: boolean;
         aggregates: Array<AggregateSpec>;
         readAccess?: ViewerReadAccess;
@@ -63,7 +70,10 @@ export type ReadContextDB = {
         modelIDs: Array<string>;
         filter?: DocumentFilter;
         owner?: string;
-        catalogID?: string;
+        catalogRef?: {
+            owner: string;
+            id: string;
+        };
         count: boolean;
         aggregates: Array<AggregateSpec>;
         groupBy: Array<{
@@ -86,7 +96,10 @@ export type AggregateScope = {
     modelIDs: Array<string>;
     filter?: DocumentFilter;
     owner?: string;
-    catalogID?: string;
+    catalogRef?: {
+        owner: string;
+        id: string;
+    };
 };
 /**
  * Connection value returned by {@link QueryContext.resolveConnection}. Extends
@@ -103,7 +116,10 @@ export type ScopedConnection = Connection<DocumentNode> & {
 export type ResolveAggregateParams = {
     filter?: DocumentFilter;
     owner?: string;
-    catalogID?: string;
+    catalogRef?: {
+        owner: string;
+        id: string;
+    };
     count: boolean;
     aggregates: Array<AggregateSpec>;
 };
@@ -116,7 +132,10 @@ export type ResolveAggregateParams = {
 export type ResolveGroupedAggregateParams = {
     filter?: DocumentFilter;
     owner?: string;
-    catalogID?: string;
+    catalogRef?: {
+        owner: string;
+        id: string;
+    };
     count: boolean;
     aggregates: Array<AggregateSpec>;
     groupBy: Array<{
@@ -158,6 +177,176 @@ export type SubscriptionContext = {
  * Query and subscription functions requiring server implementation
  */
 export type ReadOnlyContext = QueryContext & SubscriptionContext;
+export type CatalogRuleInput = Omit<CatalogRuleValue, 'id'> & {
+    id?: string;
+};
+export type CatalogRuleValue = {
+    id: string;
+    models?: Array<string>;
+    owners?: Array<string>;
+    maxAge?: string;
+    maxAhead?: string;
+    dateField?: string;
+};
+export type CatalogValue = {
+    id: string;
+    headVersionID: string;
+    upstream?: CatalogVersionRef;
+    name: string;
+    description?: string;
+    rules: Array<CatalogRuleValue>;
+    app?: string;
+};
+export type CatalogListing = {
+    id: string;
+    app: string | null;
+    name: string;
+    deletedAt: string | null;
+    catalog: CatalogValue | null;
+};
+export type CatalogVersionRef = {
+    catalogID: string;
+    versionID: string;
+};
+export type CatalogVersion = {
+    id: string;
+    catalogID: string;
+    parents: Array<CatalogVersionRef>;
+    catalog: CatalogValue;
+};
+export type CatalogVersionConnection = {
+    edges: Array<{
+        cursor: string;
+        node: CatalogVersion;
+    }>;
+    pageInfo: {
+        endCursor: string | null;
+        hasNextPage: boolean;
+    };
+};
+export type CatalogDraft = {
+    catalogID: string;
+    baseVersionID: string;
+    dirty: boolean;
+    updateAvailable: boolean;
+    catalog: CatalogValue;
+};
+export type CatalogUpdateInput = {
+    name?: string;
+    description?: string;
+    rules?: Array<CatalogRuleInput>;
+};
+export type FetchCatalogHeadVersionParams = {
+    catalogID: string;
+    versionID: string;
+    groupID: string;
+    peerDID: string;
+    /** Aborts once another member's copy decided the lookup. */
+    signal?: AbortSignal;
+};
+export type CatalogUpstreamUnavailableReason = 'NO_LIVE_OFFER' | 'UPSTREAM_DELETED' | 'BASE_MISSING' | 'VERSION_PENDING';
+export type CatalogUpstreamStatus = {
+    upstream: CatalogVersionRef | null;
+    latestVersionID: string | null;
+    updateAvailable: boolean;
+    unavailableReason: CatalogUpstreamUnavailableReason | null;
+};
+export type CatalogUpstreamLookup = {
+    status(id: string): Promise<CatalogUpstreamStatus>;
+    held(ref: CatalogVersionRef): Promise<SignedRecord | null>;
+    fetch(params: FetchCatalogHeadVersionParams): Promise<SignedRecord | null>;
+    eligible(catalogID: string): Promise<boolean>;
+};
+export type { CatalogRuleResolutionInput } from '@kubun/store-graph';
+export type CatalogPullPreview = {
+    baseVersionID: string;
+    localRevisionID: string;
+    upstreamVersionID: string;
+    merged: CatalogDefinition & {
+        id: string;
+    };
+    conflicts: Array<CatalogRuleConflict>;
+};
+export type CatalogPullResult = {
+    catalog: CatalogListing;
+    draft: CatalogDraft | null;
+    published: boolean;
+};
+export type ResolveCatalogPullParams = {
+    id: string;
+    baseVersionID: string;
+    localRevisionID: string;
+    upstreamVersionID: string;
+    resolutions: Array<CatalogRuleResolutionInput>;
+    publish: boolean;
+};
+export type CatalogDeviceStorage = {
+    catalogID: string;
+    level: CatalogLevel | null;
+    state: 'READY' | 'NEEDS_ROUTE';
+    matchingLocalDocuments: number;
+};
+export type CustodyStatus = 'NONE' | 'PENDING' | 'PARTIAL' | 'READY';
+export type CatalogCustody = {
+    catalogID: string;
+    custodians: Array<string>;
+    accepted: Array<string>;
+    /** Named custodians whose last word is that they take no custody. */
+    declined: Array<string>;
+    status: CustodyStatus;
+};
+export type CatalogContext = {
+    previewCatalogPull(id: string): Promise<CatalogPullPreview>;
+    resolveCatalogPull(params: ResolveCatalogPullParams): Promise<CatalogPullResult>;
+    cloneCatalog(id: string): Promise<CatalogListing>;
+    catalogUpstreamStatus(id: string): Promise<CatalogUpstreamStatus>;
+    createCatalog(input: {
+        name: string;
+        description?: string;
+        rules: Array<CatalogRuleInput>;
+        app?: string;
+    }): Promise<CatalogListing>;
+    updateCatalog(id: string, input: {
+        name?: string;
+        description?: string;
+        rules?: Array<CatalogRuleInput>;
+    }): Promise<CatalogListing>;
+    deleteCatalog(id: string): Promise<boolean>;
+    deduplicateAppCatalogs(app: string, name: string): Promise<CatalogListing | null>;
+    setCatalogDeviceLevel(id: string, level: CatalogLevel): Promise<CatalogDeviceStorage>;
+    catalogDeviceStorage(id: string): Promise<CatalogDeviceStorage>;
+    catalogCustody(id: string): Promise<CatalogCustody>;
+    /**
+     * Assign the catalog's custodians, superseding the current assignment. A custodian no longer
+     * named keeps its pins until a named custodian has accepted and answered held, so an empty list
+     * releases nothing: the old custodians keep their copies.
+     */
+    setCatalogCustodians(id: string, deviceDIDs: Array<string>): Promise<CatalogCustody>;
+    /** Whether this device accepts custody assignments; kept locally, over the engine default. */
+    setDeviceCustodyEligible(eligible: boolean): Promise<boolean>;
+    /**
+     * Write the next assignment without this device. Refused (`CUSTODY_ONLY_COPY`) while no other
+     * custodian accepted the current one, unless `force`. Pins go after another custodian's receipt,
+     * or at once with `force`, which deletes nothing.
+     */
+    leaveCatalogCustody(id: string, force: boolean): Promise<CatalogCustody>;
+    catalogs(includeDeleted: boolean): Promise<Array<CatalogListing>>;
+    catalogVersions(params: {
+        id: string;
+        first: number;
+        after?: string;
+    }): Promise<CatalogVersionConnection>;
+    catalogDraft(id: string): Promise<CatalogDraft | null>;
+    editCatalogDraft(id: string, input: CatalogUpdateInput): Promise<CatalogDraft>;
+    discardCatalogDraft(id: string): Promise<boolean>;
+    publishCatalogDraft(id: string, expectedHeadVersionID: string): Promise<CatalogListing>;
+    documentScope(id: string): Promise<DocumentScopeView>;
+    retainDocument(documentID: string, options: {
+        reason?: string;
+        expiresAt?: string;
+    }): Promise<DocumentHold>;
+    releaseDocumentHold(holdID: string): Promise<boolean>;
+};
 export type AccessChecker = (doc: DocumentNode, permissionType: 'read' | 'write') => Promise<boolean>;
 export type AccessWarning = {
     message: string;
@@ -174,7 +363,6 @@ export type ReadContextParams = {
     store: ReadContextDB;
     events?: DocumentEventEmitter;
     viewerDID: string;
-    catalogID?: string;
     accessChecker?: AccessChecker;
     viewerReadAccess?: ViewerReadAccess;
     warnings?: Array<AccessWarning>;
@@ -303,4 +491,6 @@ export type MutationContext = {
  */
 export interface PluginContextMap {
 }
-export type Context = ReadOnlyContext & MutationContext & Partial<PluginContextMap>;
+export type Context = ReadOnlyContext & MutationContext & {
+    catalog?: CatalogContext;
+} & Partial<PluginContextMap>;

package/lib/context.js

@@ -1,4 +1,4 @@
-import { DocumentID } from '@kubun/id';
+import { CatalogID, DocumentID } from '@kubun/id';
 import { getKubunLogger } from '@kubun/logger';
 import { KubunAttributeKeys, KubunSpanNames } from '@kubun/protocol';
 import { defer } from '@sozai/async';
@@ -243,8 +243,9 @@ export function createReadContext(params) {
                 modelIDs,
                 filter: args.filter,
                 owner: args.owner,
-                catalogID: params.catalogID
+                catalogRef: args.catalogID == null ? undefined : CatalogID.fromString(args.catalogID).toRecordKey()
             };
+            const catalogRef = aggregateScope.catalogRef;
             const result = await traced(KubunSpanNames.DATA_QUERY, {
                 [KubunAttributeKeys.MODEL_ID]: modelIDs.join(',')
             }, async ()=>{
@@ -253,7 +254,8 @@ export function createReadContext(params) {
                     const searchResults = await store.searchDocuments({
                         query: args.search,
                         modelIDs,
-                        first: 200
+                        first: 200,
+                        catalogRef
                     });
                     if (searchResults.length === 0) {
                         if (params.complexity != null) {
@@ -314,7 +316,7 @@ export function createReadContext(params) {
                     const { entries, hasMore } = await store.queryDocuments({
                         ...args,
                         modelIDs,
-                        catalogID: params.catalogID
+                        catalogRef
                     });
                     if (params.complexity != null) {
                         params.complexity.resolverCount++;
@@ -357,7 +359,7 @@ export function createReadContext(params) {
                         const { entries, hasMore } = await store.queryDocuments({
                             ...args,
                             modelIDs,
-                            catalogID: params.catalogID,
+                            catalogRef,
                             first: UNBOUNDED_SCAN_BATCH_SIZE,
                             after: cursor
                         });
@@ -399,7 +401,7 @@ export function createReadContext(params) {
                         const { entries, hasMore } = await store.queryDocuments({
                             ...args,
                             modelIDs,
-                            catalogID: params.catalogID,
+                            catalogRef,
                             first: fetchSize,
                             after: cursor
                         });
@@ -430,7 +432,7 @@ export function createReadContext(params) {
                         const { entries, hasMore } = await store.queryDocuments({
                             ...args,
                             modelIDs,
-                            catalogID: params.catalogID,
+                            catalogRef,
                             last: fetchSize,
                             before: cursor
                         });
@@ -539,7 +541,7 @@ export function createReadContext(params) {
                     modelIDs,
                     filter: aggregateParams.filter,
                     owner: aggregateParams.owner,
-                    catalogID: aggregateParams.catalogID ?? params.catalogID,
+                    catalogRef: aggregateParams.catalogRef,
                     count: aggregateParams.count,
                     aggregates: aggregateParams.aggregates,
                     readAccess: viewerReadAccess
@@ -565,7 +567,7 @@ export function createReadContext(params) {
                     modelIDs,
                     filter: groupedParams.filter,
                     owner: groupedParams.owner,
-                    catalogID: groupedParams.catalogID ?? params.catalogID,
+                    catalogRef: groupedParams.catalogRef,
                     count: groupedParams.count,
                     aggregates: groupedParams.aggregates,
                     groupBy: groupedParams.groupBy,

package/lib/index.d.ts

@@ -1,4 +1,4 @@
-export type { AccessWarning, AggregateScope, ComplexityStats, Context, CreateMutationParams, DocumentEventEmitter, DocumentSavedEvent, MutationContext, PluginContextMap, QueryContext, ReadContextDB, ReadContextParams, ReadOnlyContext, RemoveMutationParams, ScopedConnection, SetDocumentAccessOverrideParams, SetModelAccessDefaultsParams, SetMutationParams, SubscriptionContext, UpdateMutationParams, } from './context.js';
+export type { AccessWarning, AggregateScope, CatalogContext, CatalogCustody, CatalogDeviceStorage, CatalogDraft, CatalogListing, CatalogPullPreview, CatalogPullResult, CatalogRuleInput, CatalogRuleResolutionInput, CatalogRuleValue, CatalogUpdateInput, CatalogUpstreamLookup, CatalogUpstreamStatus, CatalogUpstreamUnavailableReason, CatalogValue, CatalogVersion, CatalogVersionConnection, CatalogVersionRef, ComplexityStats, Context, CreateMutationParams, CustodyStatus, DocumentEventEmitter, DocumentSavedEvent, FetchCatalogHeadVersionParams, MutationContext, PluginContextMap, QueryContext, ReadContextDB, ReadContextParams, ReadOnlyContext, RemoveMutationParams, ResolveCatalogPullParams, ScopedConnection, SetDocumentAccessOverrideParams, SetModelAccessDefaultsParams, SetMutationParams, SubscriptionContext, UpdateMutationParams, } from './context.js';
 export { createReadContext } from './context.js';
 export { GraphQLAttachmentID, GraphQLCredentialEntryID, GraphQLDocID, } from './identifiers.js';
 export type { ExtensionResolvers, SchemaBuilderParams, SharedDefinitions, } from './schema.js';

package/lib/schema.js

@@ -1,7 +1,7 @@
-import { AttachmentID, DocumentID, DocumentModelID, decodeID, PluginNodeID } from '@kubun/id';
+import { AttachmentID, CatalogID, DocumentID, DocumentModelID, decodeID, PluginNodeID } from '@kubun/id';
 import { REFERENCE_PREFIX } from '@kubun/protocol';
 import { pascalCase } from 'change-case';
-import { extendSchema, GraphQLBoolean, GraphQLEnumType, GraphQLFloat, GraphQLID, GraphQLInputObjectType, GraphQLInt, GraphQLInterfaceType, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema, GraphQLString, isEnumType, isListType, isNonNullType, isObjectType, isScalarType, Kind, parse as parseGraphQL } from 'graphql';
+import { extendSchema, GraphQLBoolean, GraphQLEnumType, GraphQLError, GraphQLFloat, GraphQLID, GraphQLInputObjectType, GraphQLInt, GraphQLInterfaceType, GraphQLList, GraphQLNonNull, GraphQLObjectType, GraphQLSchema, GraphQLString, isEnumType, isListType, isNonNullType, isObjectType, isScalarType, Kind, parse as parseGraphQL } from 'graphql';
 import { GraphQLDateTimeISO, GraphQLDID, GraphQLDuration, GraphQLEmailAddress, GraphQLJSON, GraphQLJSONObject } from 'graphql-scalars';
 import { GraphQLAttachmentID, GraphQLCredentialEntryID, GraphQLDocID } from './identifiers.js';
 import { connectionArgs, connectionDefinitions, mutationWithClientMutationId, nodeDefinitions } from './relay.js';
@@ -358,6 +358,411 @@ const ModelAccessDefaults = new GraphQLObjectType({
             }
         })
 });
+const CatalogRuleInput = new GraphQLInputObjectType({
+    name: 'CatalogRuleInput',
+    fields: {
+        id: {
+            type: GraphQLID
+        },
+        models: {
+            type: toList(GraphQLString)
+        },
+        owners: {
+            type: toList(GraphQLString)
+        },
+        maxAge: {
+            type: GraphQLString
+        },
+        maxAhead: {
+            type: GraphQLString
+        },
+        dateField: {
+            type: GraphQLString
+        }
+    }
+});
+const CatalogRule = new GraphQLObjectType({
+    name: 'CatalogRule',
+    fields: {
+        id: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        models: {
+            type: toOuputList(GraphQLString)
+        },
+        owners: {
+            type: toOuputList(GraphQLString)
+        },
+        maxAge: {
+            type: GraphQLString
+        },
+        maxAhead: {
+            type: GraphQLString
+        },
+        dateField: {
+            type: GraphQLString
+        }
+    }
+});
+const CatalogVersionRef = new GraphQLObjectType({
+    name: 'CatalogVersionRef',
+    fields: {
+        catalogID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        versionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        }
+    }
+});
+const CatalogUpdateInput = new GraphQLInputObjectType({
+    name: 'CatalogUpdateInput',
+    fields: {
+        name: {
+            type: GraphQLString
+        },
+        description: {
+            type: GraphQLString
+        },
+        rules: {
+            type: toList(CatalogRuleInput)
+        }
+    }
+});
+const Catalog = new GraphQLObjectType({
+    name: 'Catalog',
+    fields: {
+        headVersionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        upstream: {
+            type: CatalogVersionRef
+        },
+        id: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        name: {
+            type: new GraphQLNonNull(GraphQLString)
+        },
+        description: {
+            type: GraphQLString
+        },
+        rules: {
+            type: new GraphQLNonNull(toOuputList(CatalogRule))
+        },
+        app: {
+            type: GraphQLString
+        }
+    }
+});
+const CatalogListing = new GraphQLObjectType({
+    name: 'CatalogListing',
+    fields: {
+        id: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        app: {
+            type: GraphQLString
+        },
+        name: {
+            type: new GraphQLNonNull(GraphQLString)
+        },
+        deletedAt: {
+            type: GraphQLString
+        },
+        catalog: {
+            type: Catalog
+        }
+    }
+});
+const CatalogVersion = new GraphQLObjectType({
+    name: 'CatalogVersion',
+    fields: {
+        id: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        catalogID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        parents: {
+            type: new GraphQLNonNull(toOuputList(CatalogVersionRef))
+        },
+        catalog: {
+            type: new GraphQLNonNull(Catalog)
+        }
+    }
+});
+const CatalogVersionEdge = new GraphQLObjectType({
+    name: 'CatalogVersionEdge',
+    fields: {
+        cursor: {
+            type: new GraphQLNonNull(GraphQLString)
+        },
+        node: {
+            type: new GraphQLNonNull(CatalogVersion)
+        }
+    }
+});
+const CatalogVersionPageInfo = new GraphQLObjectType({
+    name: 'CatalogVersionPageInfo',
+    fields: {
+        endCursor: {
+            type: GraphQLString
+        },
+        hasNextPage: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        }
+    }
+});
+const CatalogVersionConnection = new GraphQLObjectType({
+    name: 'CatalogVersionConnection',
+    fields: {
+        edges: {
+            type: new GraphQLNonNull(toOuputList(CatalogVersionEdge))
+        },
+        pageInfo: {
+            type: new GraphQLNonNull(CatalogVersionPageInfo)
+        }
+    }
+});
+const CatalogDraft = new GraphQLObjectType({
+    name: 'CatalogDraft',
+    fields: {
+        catalogID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        baseVersionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        dirty: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        },
+        updateAvailable: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        },
+        catalog: {
+            type: new GraphQLNonNull(Catalog)
+        }
+    }
+});
+const CatalogDeviceLevel = new GraphQLEnumType({
+    name: 'CatalogDeviceLevel',
+    values: {
+        KNOWN: {},
+        OFFLINE: {},
+        SERVE_ONLY: {}
+    }
+});
+const CatalogLevelState = new GraphQLEnumType({
+    name: 'CatalogLevelState',
+    values: {
+        READY: {},
+        NEEDS_ROUTE: {}
+    }
+});
+const CatalogDeviceStorage = new GraphQLObjectType({
+    name: 'CatalogDeviceStorage',
+    fields: {
+        catalogID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        level: {
+            type: CatalogDeviceLevel
+        },
+        state: {
+            type: new GraphQLNonNull(CatalogLevelState)
+        },
+        matchingLocalDocuments: {
+            type: new GraphQLNonNull(GraphQLInt)
+        }
+    }
+});
+const CustodyStatus = new GraphQLEnumType({
+    name: 'CustodyStatus',
+    values: {
+        NONE: {},
+        PENDING: {},
+        PARTIAL: {},
+        READY: {}
+    }
+});
+const CatalogCustody = new GraphQLObjectType({
+    name: 'CatalogCustody',
+    fields: {
+        catalogID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        custodians: {
+            type: new GraphQLNonNull(toOuputList(GraphQLString))
+        },
+        accepted: {
+            type: new GraphQLNonNull(toOuputList(GraphQLString))
+        },
+        declined: {
+            type: new GraphQLNonNull(toOuputList(GraphQLString))
+        },
+        status: {
+            type: new GraphQLNonNull(CustodyStatus)
+        }
+    }
+});
+const DocumentRetainHold = new GraphQLObjectType({
+    name: 'DocumentRetainHold',
+    fields: {
+        id: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        documentID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        reason: {
+            type: GraphQLString
+        },
+        expiresAt: {
+            type: GraphQLDateTimeISO,
+            resolve: (hold)=>hold.expiresAt == null ? null : new Date(hold.expiresAt)
+        }
+    }
+});
+const DocumentAvailability = new GraphQLEnumType({
+    name: 'DocumentAvailability',
+    values: {
+        LOCAL: {},
+        UNAVAILABLE: {}
+    }
+});
+const DocumentScope = new GraphQLObjectType({
+    name: 'DocumentScope',
+    fields: {
+        scope: {
+            type: new GraphQLNonNull(GraphQLString)
+        },
+        availability: {
+            type: DocumentAvailability
+        },
+        retained: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        },
+        refs: {
+            type: new GraphQLNonNull(toOuputList(GraphQLString))
+        }
+    }
+});
+const CatalogUpstreamUnavailableReason = new GraphQLEnumType({
+    name: 'CatalogUpstreamUnavailableReason',
+    values: {
+        NO_LIVE_OFFER: {},
+        UPSTREAM_DELETED: {},
+        BASE_MISSING: {},
+        VERSION_PENDING: {}
+    }
+});
+const CatalogUpstreamStatus = new GraphQLObjectType({
+    name: 'CatalogUpstreamStatus',
+    fields: {
+        upstream: {
+            type: CatalogVersionRef
+        },
+        latestVersionID: {
+            type: GraphQLID
+        },
+        updateAvailable: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        },
+        unavailableReason: {
+            type: CatalogUpstreamUnavailableReason
+        }
+    }
+});
+const CatalogRuleConflict = new GraphQLObjectType({
+    name: 'CatalogRuleConflict',
+    fields: {
+        ruleID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        base: {
+            type: CatalogRule
+        },
+        local: {
+            type: CatalogRule
+        },
+        upstream: {
+            type: CatalogRule
+        }
+    }
+});
+const CatalogPullPreview = new GraphQLObjectType({
+    name: 'CatalogPullPreview',
+    fields: {
+        baseVersionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        localRevisionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        upstreamVersionID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        merged: {
+            type: new GraphQLNonNull(Catalog)
+        },
+        conflicts: {
+            type: new GraphQLNonNull(toOuputList(CatalogRuleConflict))
+        }
+    }
+});
+const CatalogPullResult = new GraphQLObjectType({
+    name: 'CatalogPullResult',
+    fields: {
+        catalog: {
+            type: new GraphQLNonNull(CatalogListing)
+        },
+        draft: {
+            type: CatalogDraft
+        },
+        published: {
+            type: new GraphQLNonNull(GraphQLBoolean)
+        }
+    }
+});
+const CatalogPullSide = new GraphQLEnumType({
+    name: 'CatalogPullSide',
+    values: {
+        LOCAL: {},
+        UPSTREAM: {}
+    }
+});
+const CatalogRuleResolutionInput = new GraphQLInputObjectType({
+    name: 'CatalogRuleResolutionInput',
+    fields: {
+        ruleID: {
+            type: new GraphQLNonNull(GraphQLID)
+        },
+        side: {
+            type: new GraphQLNonNull(CatalogPullSide)
+        }
+    }
+});
+function requireCatalog(ctx) {
+    if (ctx.catalog === undefined) throw new Error('Catalog context is unavailable');
+    return ctx.catalog;
+}
+async function catalogOperation(operation) {
+    try {
+        return await operation();
+    } catch (error) {
+        if (error instanceof Error && 'code' in error && (error.code === 'CATALOG_PULL_STALE' || error.code === 'CATALOG_RULES_EMPTY' || error.code === 'CATALOG_RULE_LIMIT_EXCEEDED' || error.code === 'INVALID_CATALOG_RULE' || error.code === 'CATALOG_DEVICE_LEVEL_DENIED' || error.code === 'CUSTODIAN_UNAVAILABLE' || error.code === 'CUSTODY_SIGNER_REQUIRED' || error.code === 'CUSTODY_ONLY_COPY' || error.code === 'DEVICE_OWNER_REQUIRED' || error.code === 'DOCUMENT_HOLD_DENIED' || error.code === 'DOCUMENT_HOLD_INVALID_EXPIRY' || error.code === 'DOCUMENT_NOT_HOLDABLE')) {
+            // biome-ignore lint/style/useErrorCause: GraphQLError retains the cause as originalError.
+            throw new GraphQLError(error.message, {
+                originalError: error,
+                extensions: {
+                    code: error.code
+                }
+            });
+        }
+        throw error;
+    }
+}
 export class SchemaBuilder {
     // Mapping of model or references IDs to their GraphQL object names
     _aliases;
@@ -540,7 +945,90 @@ export class SchemaBuilder {
         this._definitions = definitions;
         const queryFields = {
             nodes: definitions.nodesField,
-            ...definitions.queryFields
+            ...definitions.queryFields,
+            previewCatalogPull: {
+                type: new GraphQLNonNull(CatalogPullPreview),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).previewCatalogPull(args.id))
+            },
+            catalogVersions: {
+                type: new GraphQLNonNull(CatalogVersionConnection),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    first: {
+                        type: new GraphQLNonNull(GraphQLInt)
+                    },
+                    after: {
+                        type: GraphQLString
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).catalogVersions({
+                        id: args.id,
+                        first: args.first,
+                        after: args.after ?? undefined
+                    })
+            },
+            catalogUpstreamStatus: {
+                type: new GraphQLNonNull(CatalogUpstreamStatus),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).catalogUpstreamStatus(args.id)
+            },
+            catalogDraft: {
+                type: CatalogDraft,
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).catalogDraft(args.id)
+            },
+            catalogs: {
+                type: new GraphQLNonNull(toOuputList(CatalogListing)),
+                args: {
+                    includeDeleted: {
+                        type: GraphQLBoolean,
+                        defaultValue: false
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).catalogs(args.includeDeleted === true)
+            },
+            catalogDeviceStorage: {
+                type: new GraphQLNonNull(CatalogDeviceStorage),
+                args: {
+                    catalogID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).catalogDeviceStorage(args.catalogID))
+            },
+            catalogCustody: {
+                type: new GraphQLNonNull(CatalogCustody),
+                args: {
+                    catalogID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).catalogCustody(args.catalogID))
+            },
+            documentScope: {
+                type: DocumentScope,
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).documentScope(args.id)
+            }
         };
         for (const id of this._includedModelIDs){
             this._buildDocument(id);
@@ -558,6 +1046,9 @@ export class SchemaBuilder {
                     },
                     search: {
                         type: GraphQLString
+                    },
+                    catalogID: {
+                        type: GraphQLID
                     }
                 },
                 resolve: async (_, args, ctx)=>{
@@ -616,10 +1107,13 @@ export class SchemaBuilder {
                     },
                     after: {
                         type: GraphQLString
+                    },
+                    catalogID: {
+                        type: GraphQLID
                     }
                 },
                 resolve: async (_root, args, ctx)=>{
-                    const { query, models, first, after } = args;
+                    const { query, models, first, after, catalogID } = args;
                     if (query.trim() === '') {
                         throw new Error('Search query must not be empty');
                     }
@@ -637,7 +1131,8 @@ export class SchemaBuilder {
                         query,
                         modelIDs,
                         first: pageSize + 1,
-                        offset
+                        offset,
+                        catalogRef: catalogID == null ? undefined : CatalogID.fromString(catalogID).toRecordKey()
                     });
                     const hasNextPage = hits.length > pageSize;
                     const page = hasNextPage ? hits.slice(0, pageSize) : hits;
@@ -886,6 +1381,219 @@ export class SchemaBuilder {
                 }
             };
         }
+        if (this._includeMutations) {
+            this._mutations.editCatalogDraft = {
+                type: new GraphQLNonNull(CatalogDraft),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    input: {
+                        type: new GraphQLNonNull(CatalogUpdateInput)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).editCatalogDraft(args.id, args.input))
+            };
+            this._mutations.discardCatalogDraft = {
+                type: new GraphQLNonNull(GraphQLBoolean),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).discardCatalogDraft(args.id))
+            };
+            this._mutations.publishCatalogDraft = {
+                type: new GraphQLNonNull(CatalogListing),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    expectedHeadVersionID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).publishCatalogDraft(args.id, args.expectedHeadVersionID))
+            };
+            this._mutations.resolveCatalogPull = {
+                type: new GraphQLNonNull(CatalogPullResult),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    baseVersionID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    localRevisionID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    upstreamVersionID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    resolutions: {
+                        type: new GraphQLNonNull(toList(CatalogRuleResolutionInput))
+                    },
+                    publish: {
+                        type: new GraphQLNonNull(GraphQLBoolean)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).resolveCatalogPull(args))
+            };
+            this._mutations.cloneCatalog = {
+                type: new GraphQLNonNull(CatalogListing),
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).cloneCatalog(args.id))
+            };
+            this._mutations.createCatalog = {
+                type: Catalog,
+                args: {
+                    name: {
+                        type: new GraphQLNonNull(GraphQLString)
+                    },
+                    description: {
+                        type: GraphQLString
+                    },
+                    rules: {
+                        type: new GraphQLNonNull(toList(CatalogRuleInput))
+                    },
+                    app: {
+                        type: GraphQLString
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(async ()=>{
+                        const listing = await requireCatalog(ctx).createCatalog({
+                            name: args.name,
+                            description: args.description ?? undefined,
+                            rules: args.rules,
+                            app: args.app ?? undefined
+                        });
+                        return listing.catalog;
+                    })
+            };
+            this._mutations.updateCatalog = {
+                type: Catalog,
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    name: {
+                        type: GraphQLString
+                    },
+                    description: {
+                        type: GraphQLString
+                    },
+                    rules: {
+                        type: toList(CatalogRuleInput)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(async ()=>{
+                        const listing = await requireCatalog(ctx).updateCatalog(args.id, {
+                            name: args.name ?? undefined,
+                            description: args.description ?? undefined,
+                            rules: args.rules ?? undefined
+                        });
+                        return listing.catalog;
+                    })
+            };
+            this._mutations.deleteCatalog = {
+                type: GraphQLBoolean,
+                args: {
+                    id: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await requireCatalog(ctx).deleteCatalog(args.id)
+            };
+            this._mutations.deduplicateAppCatalogs = {
+                type: Catalog,
+                args: {
+                    app: {
+                        type: new GraphQLNonNull(GraphQLString)
+                    },
+                    name: {
+                        type: new GraphQLNonNull(GraphQLString)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>(await requireCatalog(ctx).deduplicateAppCatalogs(args.app, args.name))?.catalog ?? null
+            };
+            this._mutations.setCatalogDeviceLevel = {
+                type: new GraphQLNonNull(CatalogDeviceStorage),
+                args: {
+                    catalogID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    level: {
+                        type: new GraphQLNonNull(CatalogDeviceLevel)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).setCatalogDeviceLevel(args.catalogID, args.level))
+            };
+            this._mutations.setCatalogCustodians = {
+                type: new GraphQLNonNull(CatalogCustody),
+                args: {
+                    catalogID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    deviceDIDs: {
+                        type: new GraphQLNonNull(new GraphQLList(new GraphQLNonNull(GraphQLString)))
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).setCatalogCustodians(args.catalogID, args.deviceDIDs))
+            };
+            this._mutations.setDeviceCustodyEligible = {
+                type: new GraphQLNonNull(GraphQLBoolean),
+                args: {
+                    eligible: {
+                        type: new GraphQLNonNull(GraphQLBoolean)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).setDeviceCustodyEligible(args.eligible))
+            };
+            this._mutations.leaveCatalogCustody = {
+                type: new GraphQLNonNull(CatalogCustody),
+                args: {
+                    catalogID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    force: {
+                        type: GraphQLBoolean,
+                        defaultValue: false
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).leaveCatalogCustody(args.catalogID, args.force === true))
+            };
+            this._mutations.retainDocument = {
+                type: new GraphQLNonNull(DocumentRetainHold),
+                args: {
+                    documentID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    },
+                    reason: {
+                        type: GraphQLString
+                    },
+                    expiresAt: {
+                        type: GraphQLDateTimeISO
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).retainDocument(args.documentID, {
+                            reason: args.reason ?? undefined,
+                            expiresAt: args.expiresAt?.toISOString()
+                        }))
+            };
+            this._mutations.releaseDocumentHold = {
+                type: new GraphQLNonNull(GraphQLBoolean),
+                args: {
+                    holdID: {
+                        type: new GraphQLNonNull(GraphQLID)
+                    }
+                },
+                resolve: async (_root, args, ctx)=>await catalogOperation(()=>requireCatalog(ctx).releaseDocumentHold(args.holdID))
+            };
+        }
         const config = {
             query: new GraphQLObjectType({
                 name: 'Query',
@@ -1400,7 +2108,7 @@ export class SchemaBuilder {
                             return await ctx.resolveAggregate(scope.modelIDs, {
                                 filter: scope.filter,
                                 owner: scope.owner,
-                                catalogID: scope.catalogID,
+                                catalogRef: scope.catalogRef,
                                 count,
                                 aggregates
                             });
@@ -1442,7 +2150,7 @@ export class SchemaBuilder {
                             return await ctx.resolveGroupedAggregate(scope.modelIDs, {
                                 filter: scope.filter,
                                 owner: scope.owner,
-                                catalogID: scope.catalogID,
+                                catalogRef: scope.catalogRef,
                                 count,
                                 aggregates,
                                 groupBy,

package/lib/types.d.ts

@@ -6,6 +6,7 @@ export type AllConnectionArguments = ConnectionArguments & {
     orderBy?: DocumentOrderBy;
     search?: string;
     owner?: string;
+    catalogID?: string;
 };
 export type UpdateMutationInput = {
     id: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kubun/graphql",
-  "version": "0.17.2",
+  "version": "0.18.0",
   "keywords": [],
   "license": "see LICENSE.md",
   "sideEffects": false,
@@ -15,27 +15,36 @@
     "LICENSE.md"
   ],
   "dependencies": {
-    "@kubun/hlc": "^0.17.0",
-    "@kubun/id": "^0.17.0",
-    "@kubun/logger": "^0.17.0",
-    "@kubun/protocol": "^0.17.1",
-    "@sozai/async": "^0.2.1",
-    "@sozai/codec": "^0.4.0",
-    "@sozai/event": "^0.1.3",
-    "@sozai/otel": "^0.3.2",
+    "@kubun/hlc": "^0.18.0",
+    "@kubun/id": "^0.18.0",
+    "@kubun/logger": "^0.18.0",
+    "@kubun/protocol": "^0.18.0",
+    "@kubun/records": "^0.18.0",
+    "@sozai/async": "^0.4.1",
+    "@sozai/codec": "^0.4.3",
+    "@sozai/event": "^0.1.6",
+    "@sozai/otel": "^0.3.3",
     "change-case": "^5.4.4",
     "graphql": "^17.0.2",
-    "graphql-scalars": "^2.0.0",
+    "graphql-scalars": "^2.0.1",
     "multiformats": "^14.0.5"
   },
   "devDependencies": {
-    "@kokuin/capability": "^0.3.0",
-    "@kokuin/token": "^0.5.0",
-    "@kubun/db": "^0.17.0",
-    "@kubun/db-better-sqlite": "^0.17.0",
-    "@kubun/scalars": "^0.17.0",
-    "@kubun/store-graph": "^0.17.1",
-    "@kubun/test-utils": "^0.0.0"
+    "@kokuin/capability": "^0.4.2",
+    "@kokuin/token": "^0.5.1",
+    "@kubun/connector": "^0.18.0",
+    "@kubun/connector-google-calendar": "^0.18.0",
+    "@kubun/db": "^0.18.0",
+    "@kubun/db-adapter": "^0.18.0",
+    "@kubun/db-better-sqlite": "^0.18.0",
+    "@kubun/db-postgres": "^0.18.0",
+    "@kubun/models-calendar": "^0.18.0",
+    "@kubun/models-core": "^0.18.0",
+    "@kubun/scalars": "^0.18.0",
+    "@kubun/store-graph": "^0.18.0",
+    "@kubun/test-utils": "^0.0.0",
+    "@testcontainers/postgresql": "^12.2.1",
+    "kysely": "^0.29.7"
   },
   "publishConfig": {
     "access": "public"