@byline/client 4.14.1 → 4.15.0

package/dist/collection-handle.d.ts

@@ -7,7 +7,7 @@
  */
 import type { AuditLogPage, ChangeStatusResult, CollectionDefinition, CreateDocumentResult, DeleteDocumentResult, RestoreVersionResult, UnpublishResult, UpdateDocumentResult } from '@byline/core';
 import type { BylineClient } from './client.js';
-import type { AuditLogOptions, ClientDocument, ClientSearchResults, CollectionSearchOptions, CreateOptions, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, GetTreeParentOptions, HistoryOptions, PlaceTreeNodeOptions, ReindexResult, RemoveFromTreeOptions, TreeNode, TreeParentResult, UpdateOptions } from './types.js';
+import type { AuditLogOptions, ClientDocument, ClientSearchResults, CollectionSearchOptions, ConfirmScheduledPublishOptions, CreateOptions, DocumentPublishScheduleInfo, FindByIdOptions, FindByPathOptions, FindByVersionOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, GetTreeParentOptions, HistoryOptions, PlaceTreeNodeOptions, ReindexResult, RemoveFromTreeOptions, SchedulePublishOptions, TreeNode, TreeParentResult, UpdateOptions } from './types.js';
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -124,6 +124,22 @@ export declare class CollectionHandle<TFields extends Record<string, any> = Reco
      * versions of the same document.
      */
     changeStatus(documentId: string, nextStatus: string): Promise<ChangeStatusResult>;
+    /**
+     * Arm or reschedule publication of the exact current version the caller
+     * reviewed. The lifecycle requires both `changeStatus` and `publish` and
+     * validates the instant against database time.
+     */
+    schedulePublish(documentId: string, options: SchedulePublishOptions): Promise<DocumentPublishScheduleInfo>;
+    /** Re-authorize a content-edited schedule against the reviewed version. */
+    confirmScheduledPublish(documentId: string, options: ConfirmScheduledPublishOptions): Promise<DocumentPublishScheduleInfo>;
+    /**
+     * Cancel the active schedule. A null result means no schedule remained when
+     * the cancellation transaction acquired the row lock; callers must not
+     * report that outcome as a successful cancellation.
+     */
+    cancelScheduledPublish(documentId: string): Promise<DocumentPublishScheduleInfo | null>;
+    /** Read the active document-grain schedule under the same two abilities. */
+    getScheduledPublish(documentId: string): Promise<DocumentPublishScheduleInfo | null>;
     /**
      * Archive the currently-published version(s) of a document.
      */

package/dist/collection-handle.js

@@ -5,10 +5,14 @@
  *
  * Copyright (c) Infonomic Company Limited
  */
-import { applyAfterRead, assertActorCanPerform, buildSearchDocument, changeDocumentStatus, createDocument, createReadContext, createRichTextDocumentReader, deleteDocument, ERR_VALIDATION, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, restoreDocumentVersion, unpublishDocument, updateDocument, } from '@byline/core';
+import { applyAfterRead, assertActorCanPerform, buildSearchDocument, cancelDocumentScheduledPublish, changeDocumentStatus, confirmDocumentScheduledPublish, createDocument, createReadContext, createRichTextDocumentReader, deleteDocument, ERR_VALIDATION, getDocumentScheduledPublish, parseSort, parseWhere, placeTreeNode as placeTreeNodeLifecycle, populateDocuments, populateRichTextFields, removeFromTree as removeFromTreeLifecycle, resolveIdentityField, restoreDocumentVersion, scheduleDocumentPublish, unpublishDocument, updateDocument, } from '@byline/core';
 import { getReadSecurityDomain, resolveReadRequestContext, resolveReadSecurityFilters, } from './read-context.js';
 import { shapeDocument, shapePopulatedInPlace } from './response.js';
 import { assertSearchQueryLength, finalizeSearchHits } from './search.js';
+function toScheduleInfo(schedule) {
+    const { executionToken: _executionToken, executionExpiresAt: _executionExpiresAt, ...info } = schedule;
+    return info;
+}
 /**
  * A handle scoped to a single collection. Provides read (and eventually write)
  * operations against that collection's documents.
@@ -417,6 +421,36 @@ export class CollectionHandle {
         const ctx = await this.buildLifecycleContext();
         return changeDocumentStatus(ctx, { documentId, nextStatus });
     }
+    /**
+     * Arm or reschedule publication of the exact current version the caller
+     * reviewed. The lifecycle requires both `changeStatus` and `publish` and
+     * validates the instant against database time.
+     */
+    async schedulePublish(documentId, options) {
+        const ctx = await this.buildLifecycleContext();
+        return toScheduleInfo(await scheduleDocumentPublish(ctx, { documentId, ...options }));
+    }
+    /** Re-authorize a content-edited schedule against the reviewed version. */
+    async confirmScheduledPublish(documentId, options) {
+        const ctx = await this.buildLifecycleContext();
+        return toScheduleInfo(await confirmDocumentScheduledPublish(ctx, { documentId, ...options }));
+    }
+    /**
+     * Cancel the active schedule. A null result means no schedule remained when
+     * the cancellation transaction acquired the row lock; callers must not
+     * report that outcome as a successful cancellation.
+     */
+    async cancelScheduledPublish(documentId) {
+        const ctx = await this.buildLifecycleContext();
+        const schedule = await cancelDocumentScheduledPublish(ctx, { documentId });
+        return schedule == null ? null : toScheduleInfo(schedule);
+    }
+    /** Read the active document-grain schedule under the same two abilities. */
+    async getScheduledPublish(documentId) {
+        const ctx = await this.buildLifecycleContext();
+        const schedule = await getDocumentScheduledPublish(ctx, { documentId });
+        return schedule == null ? null : toScheduleInfo(schedule);
+    }
     /**
      * Archive the currently-published version(s) of a document.
      */

package/dist/index.d.ts

@@ -9,4 +9,4 @@ export { type AuditLogEntry, type AuditLogPage, type ChangeStatusResult, type Cr
 export { BylineClient, createBylineClient } from './client.js';
 export { CollectionHandle } from './collection-handle.js';
 export type { Register, RegisteredCollections } from './register.js';
-export type { AuditLogOptions, BylineClientConfig, ClientDocument, ClientSearchResults, CollectionSearchOptions, CreateOptions, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, GetTreeParentOptions, HydratedSearchHit, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, RemoveFromTreeOptions, SearchFacetBucket, SearchHit, SearchResults, SortDirection, SortSpec, TreeNode, TreeParentResult, UpdateOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, ZoneSearchOptions, } from './types.js';
+export type { AuditLogOptions, BylineClientConfig, ClientDocument, ClientSearchResults, CollectionSearchOptions, ConfirmScheduledPublishOptions, CreateOptions, DocumentPublishScheduleInfo, FilterOperators, FindByIdOptions, FindByPathOptions, FindOneOptions, FindOptions, FindResult, GetAncestorsOptions, GetSubtreeOptions, GetTreeParentOptions, HydratedSearchHit, PlaceTreeNodeOptions, PopulatedRelation, ReindexResult, RemoveFromTreeOptions, SchedulePublishOptions, SearchFacetBucket, SearchHit, SearchResults, SortDirection, SortSpec, TreeNode, TreeParentResult, UpdateOptions, WhereClause, WhereValue, WithPopulated, WithPopulatedMany, ZoneSearchOptions, } from './types.js';

package/dist/types.d.ts

@@ -6,7 +6,7 @@
  * Copyright (c) Infonomic Company Limited
  */
 import type { RequestContext } from '@byline/auth';
-import type { BylineLogger, CollectionDefinition, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchMatching, SearchProvider, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
+import type { BylineLogger, CollectionDefinition, DocumentPublishSchedule, IDbAdapter, IStorageProvider, MissingLocalePolicy, PopulateSpec, PredicateValue, QueryPredicate, ReadContext, ReadMode, RichTextPopulateFn, RichTextToTextFn, SearchFacetBucket, SearchHit, SearchMatching, SearchProvider, ServerConfig, SlugifierFn, SortSpec } from '@byline/core';
 export type { FilterOperators, PredicateValue, QueryPredicate, SearchFacetBucket, SearchHit, SearchProvider, SearchResults, SortDirection, SortSpec, } from '@byline/core';
 export interface BylineClientConfig {
     /**
@@ -417,6 +417,23 @@ export interface UpdateOptions {
      */
     availableLocales?: string[];
 }
+/** Optimistic, absolute-time input for `CollectionHandle.schedulePublish()`. */
+export interface SchedulePublishOptions {
+    /** ISO instant carrying an explicit UTC offset or `Z`. */
+    publishAt: string;
+    /** The current version the editor reviewed and intends to publish. */
+    expectedVersionId: string;
+}
+/** Reviewed current version used to re-arm a suspended publication. */
+export interface ConfirmScheduledPublishOptions {
+    expectedVersionId: string;
+}
+/**
+ * Editorial schedule state exposed by the client API. The execution token and
+ * its lease expiry are deliberately absent: they are internal fencing
+ * credentials owned by the sweep, not document metadata.
+ */
+export type DocumentPublishScheduleInfo = Omit<DocumentPublishSchedule, 'executionToken' | 'executionExpiresAt'>;
 /**
  * Options for `CollectionHandle.placeTreeNode(documentId, options)`. Places or
  * moves a node within the collection's single-parent ordered tree — one upsert

package/package.json

@@ -2,7 +2,7 @@
   "name": "@byline/client",
   "private": false,
   "license": "MPL-2.0",
-  "version": "4.14.1",
+  "version": "4.15.0",
   "engines": {
     "node": ">=20.9.0"
   },
@@ -44,8 +44,8 @@
   ],
   "dependencies": {
     "uuid": "^14.0.2",
-    "@byline/core": "4.14.1",
-    "@byline/auth": "4.14.1"
+    "@byline/auth": "4.15.0",
+    "@byline/core": "4.15.0"
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.9",
@@ -58,8 +58,8 @@
     "tsx": "^4.23.12",
     "typescript": "^7.0.2",
     "vitest": "^4.1.11",
-    "@byline/search-postgres": "4.14.1",
-    "@byline/db-postgres": "4.14.1"
+    "@byline/search-postgres": "4.15.0",
+    "@byline/db-postgres": "4.15.0"
   },
   "publishConfig": {
     "access": "public",