import { AbortablePromise, EngineError, EngineErrorCode, deletedAnnotationsOf, encodeAnnotKey, hasAnnotationResources, opIdOf, resolveAnnotationResources, withFileFromResource, type AnnotationResourceRole, type AnnotationCreateOptions, type AnnotationUpdateOptions, type SessionEventPublisher, type WireAnnotationResources, type AnnotationAppearanceImageOptions, type AnnotationAppearanceImagesResult, type AnnotationDraft, type AnnotationList, type AnnotationPatch, type AnnotationRef, type AnnotationCreateResult, type AnnotationDeleteResult, type AnnotationFlattenResult, type AnnotationPosition, type AnnotationReorderResult, type FlattenWriteOptions, type AnnotationUpdateResult, type DocumentEventInit, type MutationMeta, type PageAnnotationsService, type PageNetworkRenderFormat, type PageRef, type WriteOptions, checkImageQuality, } from '@embedpdf/engine-core/runtime'; import { AnnotationCreateResultSchema, AnnotationDeleteResultSchema, AnnotationListSchema, AnnotationFlattenResultSchema, AnnotationReorderResultSchema, AnnotationUpdateResultSchema, annotationAppearancesImageOptionsToWire, wirePaths, tokenPinOf, } from '@embedpdf/engine-core/wire'; import { parseAppearanceForm } from './appearanceForm'; import { buildAnnotationMutationForm } from './buildMutationForm'; import type { ManifestAccessor } from './CloudDocumentHandle'; import type { CloudWrite, CloudWrites } from './CloudWrites'; import { planesInherited } from './planes'; import { withObjectNumbers } from '../shared/withObjectNumbers'; import type { HttpClient } from '../transport/HttpClient'; /** * Cloud-side page annotation service. Mirrors the local wiring: each * call produces an `AbortablePromise` that propagates `signal.abort()` * down to `fetch` and validates the JSON response with the wire-stable * Zod schema. * * Reads use immutable versioned layer URLs discovered from the * manifest. Mutations use unversioned layer URLs and are never cached. */ export class CloudPageAnnotationsService implements PageAnnotationsService { constructor( private readonly http: HttpClient, private readonly docId: string, private readonly layerName: string, private readonly pageRef: PageRef, private readonly isClosed: () => boolean, private readonly manifest: ManifestAccessor, private readonly publisher: SessionEventPublisher, private readonly writes: CloudWrites, ) {} list(): AbortablePromise { if (this.isClosed()) { return AbortablePromise.rejectReason( new EngineError(EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`), ); } return AbortablePromise.run(async (signal) => { const buildPath = async (s: AbortSignal): Promise => { const manifest = await this.manifest.get(s); const pageObjectNumber = this.pageRef.objectNumber; const page = manifest.pages.find((p) => p.page.objectNumber === pageObjectNumber); if (!page) { throw new EngineError( EngineErrorCode.NotFound, `no page with object number ${pageObjectNumber} in document ${this.docId}`, ); } // Plane-scope rule: the list depends on the `annotations` plane. A // base's own annotations are simply visible through an inheriting // layer, so every visitor reads one doc-level URL served from the // base session. const pin = tokenPinOf('annotations', manifest.engine); return planesInherited(manifest, ['annotations']) ? wirePaths.docPageAnnotations( this.docId, this.pageRef, page.cache.annotationVersion, pin, ) : wirePaths.layerPageAnnotations( this.docId, this.layerName, this.pageRef, page.cache.annotationVersion, pin, ); }; return this.http.getJsonWithRefresh( buildPath, (raw) => AnnotationListSchema.parse(raw), async (s) => { await this.manifest.refresh(s); }, signal, ); }); } renderAppearances( options: AnnotationAppearanceImageOptions = {}, ): AbortablePromise { if (this.isClosed()) { return AbortablePromise.rejectReason( new EngineError(EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`), ); } return AbortablePromise.run(async (signal) => { checkImageQuality(options.quality); // The cloud appearance endpoint is always content-addressed, so the URL // must carry an explicit network format (PNG/WebP). Default to WebP when // the caller omits it, matching render.image(). const format: PageNetworkRenderFormat = options.format ?? 'webp'; const buildPath = async (s: AbortSignal): Promise => { const manifest = await this.manifest.get(s); const pageObjectNumber = this.pageRef.objectNumber; const page = manifest.pages.find((p) => p.page.objectNumber === pageObjectNumber); if (!page) { throw new EngineError( EngineErrorCode.NotFound, `no page with object number ${pageObjectNumber} in document ${this.docId}`, ); } const wireToken = annotationAppearancesImageOptionsToWire( { ...options, format }, { annotationVersion: page.cache.annotationVersion, pin: tokenPinOf('annotationAppearances', manifest.engine), }, ); // Same `annotations` plane switch as list(): the appearance // batch shares too. return planesInherited(manifest, ['annotations']) ? wirePaths.docPageAnnotationAppearances(this.docId, this.pageRef, wireToken) : wirePaths.layerPageAnnotationAppearances( this.docId, this.layerName, this.pageRef, wireToken, ); }; const form = await this.http.getFormDataWithRefresh( buildPath, async (s) => { await this.manifest.refresh(s); }, signal, ); return parseAppearanceForm(form); }); } /** * One of the annotation's resources. `file` is a read over the immutable * `attachment-files` leaf, pinned by the manifest's `attachmentsVersion` * (annotation-level files re-key on the same pin as document-level ones), * with the same stale-404 refresh retry as {@link list}. `appearance` is a * derived read (no-store), like {@link exportAppearance}. Both address the * annotation by the same `:annotKey` update()/delete() use. */ downloadResource(ref: AnnotationRef, role: AnnotationResourceRole): AbortablePromise { if (this.isClosed()) { return AbortablePromise.rejectReason( new EngineError(EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`), ); } if (ref.page.objectNumber !== this.pageRef.objectNumber) { return AbortablePromise.rejectReason( new EngineError( EngineErrorCode.InvalidArg, `ref.page ${ref.page.objectNumber} != page ${this.pageRef.objectNumber}`, ), ); } const annotKey = encodeAnnotKey(ref); if (role === 'appearance') { return AbortablePromise.run(async (signal) => this.http.getBytes( wirePaths.layerAnnotationAppearanceResource( this.docId, this.layerName, this.pageRef, annotKey, ), signal, ), ); } return AbortablePromise.run(async (signal) => { const buildPath = async (s: AbortSignal): Promise => { const manifest = await this.manifest.get(s); // A FileAttachment annotation's bytes depend on both planes — // the annotation must exist in this view (`annotations`) and the // byte pin is `attachmentsVersion` (`attachments`). const pin = tokenPinOf('attachments', manifest.engine); return planesInherited(manifest, ['annotations', 'attachments']) ? wirePaths.docAnnotationFile( this.docId, this.pageRef, annotKey, manifest.attachmentsVersion, pin, ) : wirePaths.layerAnnotationFile( this.docId, this.layerName, this.pageRef, annotKey, manifest.attachmentsVersion, pin, ); }; const file = await this.http.getFileWithRefresh( buildPath, async (s) => { await this.manifest.refresh(s); }, signal, ); return file.bytes; }); } create( draft: AnnotationDraft, options: AnnotationCreateOptions = {}, ): AbortablePromise { if (this.isClosed()) { return AbortablePromise.rejectReason( new EngineError(EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`), ); } let opId: string; try { opId = opIdOf(options); } catch (err) { return AbortablePromise.rejectReason(err); } const { resources, objectNumber } = options; // A `File` brings its name and type; the bytes travel without them. const data = withFileFromResource(draft, resources); const path = withObjectNumbers( wirePaths.layerPageAnnotationsCreate(this.docId, this.layerName, this.pageRef), { objectNumber }, ); return AbortablePromise.run((signal) => this.writes.run( opId, signal, async (write) => { // Without resources the request is the plain JSON POST of the data; // with them it is multipart (see `buildAnnotationMutationForm`). const wireResources = await resolveAnnotationResources(resources); const parse = (raw: unknown) => AnnotationCreateResultSchema.parse(raw); const result = await write.send((sent) => hasAnnotationResources(wireResources) ? this.http.postMultipartJson( path, buildAnnotationMutationForm(data, wireResources), parse, signal, sent, ) : this.http.postJson(path, data, parse, signal, sent), ); return this.absorbMutation(opId, result, 'annotations.created'); }, [objectNumber], ), ); } update( ref: AnnotationRef, patch: AnnotationPatch, options: AnnotationUpdateOptions = {}, ): AbortablePromise { if (this.isClosed()) { return AbortablePromise.rejectReason( new EngineError(EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`), ); } let opId: string; try { opId = opIdOf(options); } catch (err) { return AbortablePromise.rejectReason(err); } const { resources } = options; if (ref.page.objectNumber !== this.pageRef.objectNumber) { return AbortablePromise.rejectReason( new EngineError( EngineErrorCode.InvalidArg, `ref.page ${ref.page.objectNumber} != page ${this.pageRef.objectNumber}`, ), ); } const path = wirePaths.layerAnnotationByKey( this.docId, this.layerName, this.pageRef, encodeAnnotKey(ref), ); return AbortablePromise.run((signal) => this.writes.run(opId, signal, async (write) => { const wireResources = await resolveAnnotationResources(resources); const result = await this.patchMutation(write, path, { patch }, wireResources, signal); return this.absorbMutation(opId, result, 'annotations.updated'); }), ); } /** PATCH as plain JSON, or as multipart when resources came with the patch. */ private patchMutation( write: CloudWrite, path: string, body: object, resources: WireAnnotationResources, signal: AbortSignal, ): Promise { const parse = (raw: unknown) => AnnotationUpdateResultSchema.parse(raw); return write.send((sent) => hasAnnotationResources(resources) ? this.http.patchMultipartJson( path, buildAnnotationMutationForm(body, resources), parse, signal, sent, ) : this.http.patchJson(path, body, parse, signal, sent), ); } delete(ref: AnnotationRef, options?: WriteOptions): AbortablePromise { if (this.isClosed()) { return AbortablePromise.rejectReason( new EngineError(EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`), ); } let opId: string; try { opId = opIdOf(options); } catch (err) { return AbortablePromise.rejectReason(err); } if (ref.page.objectNumber !== this.pageRef.objectNumber) { return AbortablePromise.rejectReason( new EngineError( EngineErrorCode.InvalidArg, `ref.page ${ref.page.objectNumber} != page ${this.pageRef.objectNumber}`, ), ); } const path = wirePaths.layerAnnotationByKey( this.docId, this.layerName, this.pageRef, encodeAnnotKey(ref), ); return AbortablePromise.run((signal) => this.writes.run(opId, signal, async (write) => { const result = await write.send((sent) => this.http.deleteJson( path, (raw) => AnnotationDeleteResultSchema.parse(raw), signal, sent, ), ); return this.absorbDelete(opId, result); }), ); } reorder( refs: AnnotationRef[], position: AnnotationPosition, options?: WriteOptions, ): AbortablePromise { if (this.isClosed()) { return AbortablePromise.rejectReason( new EngineError(EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`), ); } let opId: string; try { opId = opIdOf(options); } catch (err) { return AbortablePromise.rejectReason(err); } // The page is part of the URL; the worker validates per-ref consistency // again, but rejecting up front gives a cleaner error from the client side. for (const r of refs) { if (r.page.objectNumber !== this.pageRef.objectNumber) { return AbortablePromise.rejectReason( new EngineError( EngineErrorCode.InvalidArg, `reorder ref points at page ${r.page.objectNumber}; service is bound to page ${this.pageRef.objectNumber}`, ), ); } } const path = wirePaths.layerPageAnnotationsReorder(this.docId, this.layerName, this.pageRef); return AbortablePromise.run((signal) => this.writes.run(opId, signal, async (write) => { const result = await write.send((sent) => this.http.postJson( path, { refs, position }, (raw) => AnnotationReorderResultSchema.parse(raw), signal, sent, ), ); // A reorder moves only the annotations: widgets have their own order. this.manifest.apply(result.meta, ['annotations']); this.publisher.publishWrite(opId, { type: 'annotations.reordered', page: this.pageRef, ...result, }); return result; }), ); } flatten( refs: AnnotationRef[], options?: FlattenWriteOptions, ): AbortablePromise { const usage = options?.usage ?? 'display'; if (this.isClosed()) { return AbortablePromise.rejectReason( new EngineError(EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`), ); } let opId: string; try { opId = opIdOf(options); } catch (err) { return AbortablePromise.rejectReason(err); } for (const r of refs) { if (r.page.objectNumber !== this.pageRef.objectNumber) { return AbortablePromise.rejectReason( new EngineError( EngineErrorCode.InvalidArg, `flatten ref points at page ${r.page.objectNumber}; service is bound to page ${this.pageRef.objectNumber}`, ), ); } } const path = wirePaths.layerPageAnnotationsFlatten(this.docId, this.layerName, this.pageRef); return AbortablePromise.run((signal) => this.writes.run(opId, signal, async (write) => { const result = await write.send((sent) => this.http.postJson( path, { refs, usage }, (raw) => AnnotationFlattenResultSchema.parse(raw), signal, sent, ), ); // Nothing applied comes back without a cache delta: no artifact, no // coherence bump, no event. if (result.meta.cacheDelta === null) return result; // Flatten bakes annotations and form fields into page content. this.manifest.apply(result.meta, ['content', 'annotations', 'forms']); this.publisher.publishWrite(opId, { type: 'annotations.flattened', ...result }); return result; }), ); } exportAppearance(refs: AnnotationRef[]): AbortablePromise { if (this.isClosed()) { return AbortablePromise.rejectReason( new EngineError(EngineErrorCode.DocNotOpen, `document ${this.docId} is closed`), ); } for (const r of refs) { if (r.page.objectNumber !== this.pageRef.objectNumber) { return AbortablePromise.rejectReason( new EngineError( EngineErrorCode.InvalidArg, `exportAppearance ref points at page ${r.page.objectNumber}; service is bound to page ${this.pageRef.objectNumber}`, ), ); } } // A read (gated by doc.download server-side): no absorb, no event. return AbortablePromise.run(async (signal) => this.http.postJsonBytes( wirePaths.layerPageAnnotationsAppearance(this.docId, this.layerName, this.pageRef), { refs }, signal, ), ); } /** * Patch the cached manifest, then publish the mutation to the document's * event stream (in that order — listeners reading the manifest in their * callback must see post-mutation state). Each call site pairs the event * `type` with the matching result by construction; the cast localizes that * pairing here instead of widening every site. */ /** A delete's event names what went, for listeners that didn't delete it. */ private absorbDelete(opId: string, result: AnnotationDeleteResult): AnnotationDeleteResult { this.manifest.apply(result.meta, ['annotations']); this.publisher.publishWrite(opId, { type: 'annotations.deleted', page: this.pageRef, deleted: deletedAnnotationsOf(result), ...result, }); return result; } private absorbMutation( opId: string, result: T, type: 'annotations.created' | 'annotations.updated', ): T { this.manifest.apply(result.meta, ['annotations']); this.publisher.publishWrite(opId, { type, page: this.pageRef, ...result, } as unknown as DocumentEventInit); return result; } }