Files
qbit-printing/docs/OPERATOR-CATALOG.md
james.maesandClaude Fable 5.2 1bf13be26e feat: operators read print jobs; retire the Remove actions; plain refusal messages
Operators read print jobs, read only. PrintingReadPermission accepted
printing_operator for print stations and printers and required
printing_admin for print jobs, so a person who prints could not see what
was printed. A holder of printing_operator now has every read shape on
printing_job that an administrator has (query, get, count, aggregate,
export) and sees every job of the tenant, with the same fields; the table
has no field for the document, its storage reference or the retained
binding. Control history and deletion history stay administrator-only and
nobody gains a write.

Retire the Remove actions. Delete (RC.3) keeps job history and records
who deleted what, so the older archive actions duplicated it on the
screens. Removed: the processes printingRemoveDevices and
printingRemoveSelectedPrinters and the control action Action.REMOVE. No
HTTP or agent route called them; the REVOKE control still resolves to
printingRevokeDevices. PrintingService.removePrinter and removeDevice
stay as service methods, and records archived earlier behave as before.

Refusals say what happened and what to do, and name no framework. The
permission checks, the 403 text of the native and legacy routes, the
control-action sign-in text and the OpenAPI descriptions are reworded;
statuses, error codes and JSON field names are unchanged. A host may give
its application's display name with PrintingQBitConfig.withProductName;
the default is "this application".

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-13 08:15:30 -06:00

4.9 KiB
Raw Permalink Blame History

Operator catalog and queue media

QQQ Printing 1.0.0 includes native printing extension 2.3.0, paired with Windows connector 1.0.1. Extension 2.2.0 introduced rendering; 2.3.0 adds this operator/media API. Existing administrator and device routes keep their permissions; this is an additive operator API, not a device bearer API.

Hosts grant printing_operator and the printing_tenant security key. The native printingSubmit process remains the domain write permission. Current device and printer table/record security, credential scopes and client-channel ceilings apply on every operation. Since 1.2.0 an operator also reads the tenant's print jobs through the native table (read only, every job of the tenant; see the changelog). Command and deletion history, table writes, enrollment and device management remain administrator-only. Hosts may add destination locks. Native callbacks cannot replace the initiating actor, session, instance, service or row-security context. Submission rechecks current process, credential, channel and destination authority after loading/storage callbacks and before commit. The backend process is hidden and has no base64-entry form. Echo obtains its user selections from the catalog; backend metadata also references native printer and format possible-value sources.

  • GET /qqq/v1/qbit/printing/operator/printers?limit=50&after=... returns at most 200 authorized approved/exposed printers, in stable printer-row-ID order. The opaque next cursor advances over at most limit candidate rows even if parent device security hides every candidate. Continue until nextCursor is null.
  • POST /qqq/v1/qbit/printing/operator/jobs accepts requestId, printerRowId, title, format (PDF or ZPL), contentBase64 and optional options. The native printer row determines the device and opaque Windows queue identity. requestId is 1–128 characters from letters, digits, ., _, :, -. The authenticated actor and tenant scope the stable key; callers cannot supply actor identity or an internal idempotency key. The response is the existing job receipt after durable commit. Changed requests conflict instead of reprinting.
  • GET /qqq/v1/qbit/printing/operator/requests/{requestId} returns only that actor's exact accepted request, or 404. It does not enqueue, read document bytes, or initialize settings. Current destination read authority remains required; later loss of exposure alone does not erase the acceptance receipt. Lookup checks the original accepted native printer-row ID. Deleting that row and creating another with the same device/queue pair does not transfer history.

Each catalog entry has printerRowId, deviceId, printerId, effective name, deviceName, status, formats, mediaProfiles, and optional description and location. These names are presentation; the stable row identity selects a queue.

Media profiles report actual Windows queue defaults. Their typed facts are id, revision (lowercase SHA-256), name, widthMicrons, heightMicrons, dpiX, dpiY, source: WINDOWS_QUEUE_DEFAULT, applyMode: DRIVER_DEFAULT. Unknown or unsupported driver facts produce an empty list. The initial client reports one configured default; the wire bound is 32. Dimensions are 1–2,000,000 microns and DPI is 1–9600. Names are at most 512 characters. Unknown additive reported facts are ignored when canonicalizing; known required facts remain validated. Arbitrary page-size values are never interpreted as a Windows stock change. Profile and selection IDs share the protocol's 128-character URL-safe ID bound.

Select exact reported media with options.mediaProfile: {id, revision}. The selection is immutable job intent and accepts no extra fields. New submissions reject stale/missing profiles before admission/storage writes; exact accepted replays remain accepted. The capable Windows agent rechecks its actual current default before spooling. Selected-media dispatch requires the current agent capability printer-media-v1, including after reconnect/downgrade. Legacy inventory without profiles clears stale media facts. Omitted selection preserves ordinary existing queue behavior. An explicit job paper size instead uses both paperWidthMm and paperHeightMm (positive, at most 2000 mm); it cannot be combined with mediaProfile. The matching connector applies that job paper without changing the machine-wide queue defaults. Select media matching the loaded stock and calibrate the physical printer after changing label sizes.

Generated/retained source authorization belongs to the configured source owner. The retained facade shares this operator permission and destination boundary; it preserves its atomic accepted source/actor/request binding. Barcode fit and encoding remain the renderer's job.

QUEUED is durable acceptance; SPOOLED means spooler acceptance. Neither is physical output confirmation. These tests use synthetic bytes and no real printer.