Skip to content
ContractSpec
Start here

Package manual · domains

·Content, growth and creator operations

lib.creator-operations-runtime

Reusable transactional creator operations.

domainslibraryv0.2.4experimentalserverbunnode
@lssm-tech/lib.creator-operations-runtime
bun add @lssm-tech/lib.creator-operations-runtime
Package source ↗Manifest ↗

Manifest declarations describe the current workspace; they do not verify registry publication or runtime execution.

Package guide

Reusable creator campaign lifecycle, immutable accepted agreements, submission review, cumulative tiered CPM accrual and wallet-backed settlement orchestration.

Contracts are owned by lib.contracts-spec/creator-operations. Inject a transactional store, a trusted authority and a clock. Every authority request contains the requested parameters and evidence references; the host must verify scope, permissions, observation evidence and financial authority against canonical records. There is no default grant.

Money uses integer decimal strings with an explicit currency and scale. Tiered CPM uses per-band integer division, matching the existing Hirly calculation. Cumulative accrual subtracts previously credited units so repeated observations cannot pay flat fees twice. Accepted terms and earned balances are immutable; corrections never claw back earnings implicitly. Campaign exposure is an additional funding ceiling.

Payout reservations, debits and history commit atomically. Unknown outcomes retain their reservation; reconciliation does not resubmit. The provider port is shared by Stripe, PayPal and manual settlement; each host adapter must verify the exact rail, destination, unit conversion and settlement evidence before claiming payment.

Accrual v2 payout batches (./accrual-v2-payout-batch, ./accrual-v2-payout-eligibility, ./accrual-v2-payout-settlement) reference existing credited obligations by id and hold each one so the wallet counts it as reserved; approval binds the exact ids, count, total and digest, settlement is recorded by finance with evidence for the exact total, and a separate reconciliation either debits each obligation or voids the batch and releases its holds. An unknown settlement outcome keeps the funds held. ./accrual-v2-adjustment-line turns each confirmed finalize adjustment into one approval-gated credit line or a recorded receivable; it never debits. No path moves money or calls a payment provider.

FINANCE-01h: ./accrual-v2-work-hold lets only the support operator assigned to an open support case (a host-bound case port and trusted work-hold policy) open or resolve a dispute; ./accrual-v2-publication-proof binds the accepted campaign mode and requires every publication slot 1..publicationCount acknowledged before a publishing mode completes; ./accrual-v2-receivable reviews (lifting a new payout block) and resolves receivable lines without money movement; ./accrual-v2-payout-items and ./accrual-v2-payout-narrowing settle, reconcile and release batch items individually with append-only approval narrowing, approved adjustment credits are batchable, and ./accrual-v2-payout-export returns the payout batch CSV. No provider is called.

FINANCE-01i: ./compensation-terms-service keeps campaign compensation terms versions (a draft revised in place, owner-confirmed immutable versions, an edit after confirmation opens a new version, one draft per campaign) with view, save and confirm; confirming a later version writes one immutable supersession in the same transaction (./compensation-terms-supersession). ./compensation-terms-preview is a nonbinding preview through the real calculator (illustrative, never payable, persists nothing). Agreement accept v2 binds the campaign's current latest confirmed terms version and refuses any other block with CREATOR_TERMS_MISMATCH.

This is additive capability extraction. Existing Hirly deployments have not migrated and its 213-operation parity inventory is not certified by these package tests.

training contains the pure creator-training state transition extracted from Hirly's current API behavior: locale, module views, quiz outcomes, micro-events and acknowledgement state. Passed modules remain completed after a later failed quiz; updates use optimistic versions and immutable snapshots. Hosts still validate course/module membership and quiz evidence, persist request receipts and own migration. Spanish locale support is additive.

training-service adds authorized initialization and durable updates. Configure the initial locale explicitly (Hirly uses fr) and a transactional CreatorTrainingStore. Request receipts bind the full parsed event, creator, course, scope and expected version. Exact retry returns the recorded state; altered request IDs fail. Host authority validates course/module membership and quiz evidence before any read or write.

Result-only legacy training receipts are rejected by default because they cannot prove exact input. Set legacyReplay: 'preserve_native' only in a reviewed native compatibility adapter to replay the stored result for the same course without mutation. Imported legacy IDs remain reserved and cannot become new exact-input update receipts.

training-course validates module, quiz, progress-event and locale membership against a versioned course definition. Call it from the training authorization hook before verifying quiz results. It does not authenticate creators or prove that a quiz was passed.

createCreatorTrainingAuthority composes authorized course loading, membership checks and server-owned quiz-result verification. The returned function can be passed directly to CreatorTrainingService.authorize. It rejects mismatched course scope and claimed quiz outcomes; the loader still owns creator enrollment/identity authorization.

training-progress projects recorded module completion against an authorized course revision. Duplicate completions count once; removed module IDs are reported separately and cannot inflate completion. Quiz outcomes do not implicitly rewrite native historical completion. The summary awards no XP or qualification.

CreatorTrainingProgressService authorizes the creator/course binding before reading stored progress. Missing training state remains absent; dashboard reads do not initialize progress or emit training receipts. The configured store may still use transactional locks.

training-quiz scores submitted answers against a private server-owned versioned key, preserving rounded percentage thresholds. Missing answers are incorrect; unknown question/option identifiers and malformed keys fail validation. Persist attempt evidence server-side and feed its result to the training authority; never trust a browser score.

CreatorTrainingQuizService authorizes exact quiz revisions, scores privately and records attempt receipts through an injected atomic store. The receipt contains submitted answers and scoring results, never the answer key. Attempt replay rejects changed inputs and does not itself update training progress. Durable attempt storage is still required.

The source-bound quiz compatibility script compares every achievable score across Hirly's localized quiz packs and records source hashes. Use scripts/check-creator-quiz-compatibility.ts --source-root <creator-platform> to refresh that evidence when native content changes. No answer keys are written to the report.

CreatorQuizCompletionService scores/persists an attempt before deriving a training quiz event from its server result. Its deterministic completion request identity prevents duplicate progress writes. A version conflict leaves scoring durable and can be retried against the correct training version; these are two recoverable stages, not one atomic transaction. Both underlying services retain their authorization hooks.

Completion passes its scored attempt into the training authorization hook. The service checks scope/creator/course/module/quiz/result binding before invoking that hook; host authorization can compare the supplied receipt with durable attempt storage. Supplied evidence is not intrinsically trusted and direct event updates retain their existing authority requirements.

createStoredCreatorQuizVerifier plugs into createCreatorTrainingAuthority.verifyQuiz. It requires completion attempt evidence, verifies creator/course/module/result binding, and compares the full receipt with private durable storage. Enrollment authorization must run first, and only trusted scorers may write attempt storage.

Relationships

THIS PACKAGElib.creator-operations-runtime50 import paths

Arrows point from a package to its direct dependency. Counts are derived from captured workspace manifests.

1 declarations

Declared capabilities

Canonical creator business runtime

Reusable transactional creator operations.

Scripts

  • buildcontractspec-bun-build build
  • build:bundlecontractspec-bun-build transpile
  • build:typescontractspec-bun-build types
  • lint:checknode ../../../../scripts/biome.cjs check .
  • testbun test
  • prebuildcontractspec-bun-build prebuild
  • typechecktsgo --noEmit
  • publish:pkgbun publish --tolerate-republish --ignore-scripts --verbose