Skip to content

Latest commit

 

History

History
408 lines (289 loc) · 21.6 KB

package-lifecycle.mdx

File metadata and controls

408 lines (289 loc) · 21.6 KB
title Package Lifecycle — API Protocol reference
navTitle Package Lifecycle
description Response payloads for the dispatcher-served packages.* lifecycle routes — the ADR-0067 commit timeline, the ADR-0033 draft batch doors.

{/* ⚠️ AUTO-GENERATED — DO NOT EDIT. Run build-docs.ts to regenerate. Hand-written docs live in the module folders under content/docs/. */}

Package lifecycle response contracts (#12038)

Response payloads for the dispatcher-served packages.* lifecycle routes — the ADR-0067 commit timeline, the ADR-0033 draft batch doors, the ADR-0070 export / adopt / duplicate family — ruled on 2026-08-27 (#12038, 1C · 2C · 3A · 4A · 5A).

Every schema here is a DESCRIBE-ONLY TRANSCRIPTION of the return type its producer already declares inline (@objectstack/metadata-protocol protocol.ts, except where a schema's own docblock says otherwise) — authoring one changes no wire byte. All of these routes are served by the runtime dispatcher ONLY (no REST twin — #12038 survey §1b), which answers through the { success, data } envelope (http-dispatcher.ts), so each schema declares the data payload, envelope-free — the same convention as PublishPackageDraftsResponseSchema and its ledger row.

Two pairs are the exception, each with a request half its producer PARSES rather than a transcription: ImportUnmanagedPackageRequestSchema / ImportUnmanagedPackageResponseSchema (ADR-0131 D6) declare a protocol verb no route serves yet, and EnsureCustomizationPackageRequestSchema / EnsureCustomizationPackageResponseSchema (ADR-0146 D3) declare the ensure door of a base's paired .custom package — see their own docblocks.

packages.publish's contract is NOT here: its producer (MetadataManager.publishPackage) already has an exact published schema, PackagePublishResultSchema in @objectstack/spec/system — re-exported below into this /api namespace (ruling 5A: re-export, never a second copy) because the route-ledger resolver looks names up only in the API protocol's entries — @objectstack/spec/api, and /api-assembled for the declarations that embed the assembled package body (#18576).

The retired PackageRollbackResponseSchema and its PackageApiContracts.rollbackPackage binding (see ./package-api-assembled.zod.ts) declared a VERSION rollback against the live COMMIT-rollback path; RollbackToPackageCommitResponseSchema below is the true contract, authored after that retirement per the ruling's sequencing (3A).

**Source:** `packages/spec/src/api/package-lifecycle.zod.ts`

TypeScript Usage

import { DiscardPackageDraftsResponseSchema, DuplicatePackageResponseSchema, EnsureCustomizationPackageRequestSchema, EnsureCustomizationPackageResponseSchema, GetPackageCustomizationsRequestSchema, GetPackageCustomizationsResponseSchema, ImportUnmanagedPackageRequestSchema, ImportUnmanagedPackageResponseSchema, ListPackageCommitsResponseSchema, PackageExportManifestSchema, PackagePublishResultSchema, ReassignOrphanedMetadataResponseSchema, RevertPackageCommitResponseSchema, RollbackToPackageCommitResponseSchema } from '@objectstack/spec/api';
import type { DiscardPackageDraftsResponse, DuplicatePackageResponse, EnsureCustomizationPackageRequest, EnsureCustomizationPackageResponse, GetPackageCustomizationsRequest, GetPackageCustomizationsResponse, ImportUnmanagedPackageRequest, ImportUnmanagedPackageResponse, ListPackageCommitsResponse, PackageExportManifest, PackagePublishResult, ReassignOrphanedMetadataResponse, RevertPackageCommitResponse, RollbackToPackageCommitResponse } from '@objectstack/spec/api';

// Validate data
const result = DiscardPackageDraftsResponseSchema.parse(data);

DiscardPackageDraftsResponse

Properties

Property Type Required Description
success boolean ✅ True exactly when nothing failed.
discardedCount number ✅ How many drafts were discarded.
failedCount number ✅ How many drafts could not be discarded.
discarded { type: string; name: string }[] ✅ Every draft that was discarded.
failed { type: string; name: string; error: string; code?: string }[] ✅ Every draft the discard could not remove.

Nested Shape: DiscardPackageDraftsResponse.discarded[number]

Property Type Required Description
type string ✅ Metadata type of the discarded draft.
name string ✅ Name of the discarded draft.

Nested Shape: DiscardPackageDraftsResponse.failed[number]

Property Type Required Description
type string ✅ Metadata type of the failing draft.
name string ✅ Name of the failing draft.
error string ✅ Why the discard failed.
code string optional Machine-readable failure code, when one was recorded.

DuplicatePackageResponse

Properties

Property Type Required Description
success boolean ✅ The duplicate's own verdict: true exactly when nothing failed AND at least one item was copied.
copiedCount number ✅ How many items were copied.
failedCount number ✅ How many items could not be copied.
targetPackageId string ✅ The new package the base was cloned into.
copied { type: string; name: string }[] ✅ Every item that was copied.
failed { type: string; name: string; error: string }[] ✅ Every item the clone could not copy.

Nested Shape: DuplicatePackageResponse.copied[number]

Property Type Required Description
type string ✅ Metadata type of the copied item.
name string ✅ Name of the copied item.

Nested Shape: DuplicatePackageResponse.failed[number]

Property Type Required Description
type string ✅ Metadata type of the failing item.
name string ✅ Name of the failing item.
error string ✅ Why copying it failed.

EnsureCustomizationPackageRequest

Properties

Property Type Required Description
basePackageId string ✅ Id of the installed base whose paired customization package is ensured (com.acme.crm → com.acme.crm.custom). The base must be installed and read-only — a writable base is customized directly — and must not itself be a customization package.

EnsureCustomizationPackageResponse

Properties

Property Type Required Description
basePackageId string ✅ The base the pair customizes.
packageId string ✅ The paired customization package: <basePackageId>.custom.
namespace string ✅ The pair's namespace: the base's namespace followed by _custom (crm → crm_custom), set explicitly and never derived from the pair's id. A new object authored into the pair is named <namespace>_<short>.
dependencyRange string ✅ The range the pair declares on its base in manifest.dependencies. A created pair declares ^<major> of the base's version at creation; an existing pair answers the range it declares, unchanged.
created boolean ✅ True when this call created the pair; false when the pair was already installed and was returned unchanged.
writable boolean ✅ Whether the pair is a writable package — the verdict the package read doors serve as writable. A created pair is writable; an existing pair delivered by code or an installed artifact is not, and its items are authored where it is built.

GetPackageCustomizationsRequest

Per-package customization read request: the base package id, no query parameters.

Properties

Property Type Required Description
packageId string ✅ The installed BASE package whose customizations are read (e.g. "com.acme.crm"). A paired <base>.custom id is refused 400 VALIDATION_ERROR with a message naming its base; an id no installed package carries answers 404.

GetPackageCustomizationsResponse

Per-package customization read: overrides, extensions and switched-off items of one installed base, and the fields and flows other packages contribute to it.

Properties

Property Type Required Description
packageId string ✅ The base package the customizations are of (the request's id).
overrides { type: string; name: string; member?: string; basedOn?: string; … }[] ✅ Every ACTIVE item of the base's paired <base>.custom package that declares overrides.package = the base and that the effective read serves over the base's item of the same name: the rows the served-override predicate admits (a declaration from any other package, and an undeclared pair item, are not listed), minus the stored rows every read declines (a shipped flow name). Ordered by type, name and member.
extensions { object: string; kind: Enum<'field' | 'validation' | 'index'>; name?: string; fields?: string[] }[] ✅ Every field, validation rule and index the paired <base>.custom package declares in an object extension (objectExtensions) of an object the base owns, one entry per member, as the extension declares it. Ordered by object, kind and name.
switchedOff { type: string; name: string }[] ✅ Every activation-ledger row (sys_metadata_activation) that records the base as its package and active: false: the base's items this deployment switched off. Ordered by type and name.
contributions { kind: Enum<'field' | 'flow'>; object: string; name: string; packageId: string }[] ✅ Every field and flow another installed package contributes to the base's objects, one entry per item and contributing package: the fields of every object extension of an object the base owns, from any package but the base and its pair, and every flow registered under such a package whose trigger object the base owns (a flow of a disabled package is not served, so not listed). Ordered by object, kind, name and package.
counts { overrides: integer; extensions: integer; switchedOff: integer; contributions: integer } ✅ Each list's length, derived from the lists in this same answer.

Nested Shape: GetPackageCustomizationsResponse.overrides[number]

Property Type Required Description
type string ✅ Metadata type of the overriding item, canonical singular (e.g. view).
name string ✅ Name of the item: the base's name it is served under.
member string optional The bundle member, for a metadata type whose identity is a pair (email_template, identified by (name, locale)): its discriminator value. Absent for a type whose identity is its name alone.
basedOn string optional The base package version the declaration records (overrides.basedOn), copied as stored and never judged. Absent when the stored body records none.
version integer optional The overriding item's stored history version, when the row carries one.

Nested Shape: GetPackageCustomizationsResponse.extensions[number]

Property Type Required Description
object string ✅ The base-owned object the member is added to.
kind Enum<'field' | 'validation' | 'index'> ✅ Which collection of the object the member joins.
name string optional The member's declared name: the field name, the validation rule name, the index name. Absent only for an index declared without a name.
fields string[] optional For an index: the fields it covers. Absent for a field or a validation.

Nested Shape: GetPackageCustomizationsResponse.switchedOff[number]

Property Type Required Description
type string ✅ The ledger row's metadata type (flow, action, position, …).
name string ✅ The switched-off item's name.

Nested Shape: GetPackageCustomizationsResponse.contributions[number]

Property Type Required Description
kind Enum<'field' | 'flow'> ✅ What is contributed: field, a field another package's object extension (objectExtensions) adds to one of the base's objects; flow, a flow another package ships whose trigger object (its start node's config.objectName) is one of the base's objects.
object string ✅ The base-owned object the item is on: the extended object, or the flow's trigger object.
name string ✅ The item's name: the field name as the extension declares it, or the flow's name.
packageId string ✅ The package that contributes the item: the extension's package, or the package the flow is registered under. Never the base and never its <base>.custom pair.

Nested Shape: GetPackageCustomizationsResponse.counts

Property Type Required Description
overrides integer ✅ overrides.length.
extensions integer ✅ extensions.length: members, not objects.
switchedOff integer ✅ switchedOff.length.
contributions integer ✅ contributions.length: items, not packages.

ImportUnmanagedPackageRequest

Properties

Property Type Required Description
manifest Record<string, any> ✅ The package to import: ONE package's assembled body, flattened — its manifest fields beside its metadata collections (objects, views, …), the shape the install door hands the manifest service. An artifact carrying packages is refused: import each package body on its own.
targetPackageId string optional Id of the NEW writable base the items are written into, in reverse-domain form. It must differ from the source id and name no installed package. Defaults to <manifest.id>-copy.
targetName string optional Display name of the new base. Defaults to the source package's name.

ImportUnmanagedPackageResponse

Properties

Property Type Required Description
sourcePackageId string ✅ The id of the package the items were copied from.
sourceVersion string optional The version the imported body declared, when it declared one.
targetPackageId string ✅ The new writable base that owns every copied item. Nothing is registered under the source id.
namespace string ✅ The base's namespace — the SOURCE package's, kept so every copied object name stays valid.
copiedCount number ✅ How many items were copied.
copied { type: string; name: string }[] ✅ Every item that was copied, in the order it was written.
strippedLocks { type: string; name: string; lock: Enum<'no-overlay' | 'no-delete' | 'full'>; reason?: string }[] ✅ Every protection lock the package shipped on a copied item and the copy does not keep, in the order the items were written. Empty when the package locked nothing.

Nested Shape: ImportUnmanagedPackageResponse.copied[number]

Property Type Required Description
type string ✅ Metadata type of the copied item.
name string ✅ Name of the copied item.

Nested Shape: ImportUnmanagedPackageResponse.strippedLocks[number]

Property Type Required Description
type string ✅ Metadata type of the copied item.
name string ✅ Name of the copied item.
lock Enum<'no-overlay' | 'no-delete' | 'full'> ✅ The lock the package shipped on the item — its protection block's lock, else its _lock. The copy carries no lock.
reason string optional The reason the package gave for that lock, verbatim. Absent when it gave none.

ListPackageCommitsResponse

Properties

Property Type Required Description
commits { id: string; operation: Enum<'apply' | 'revert'>; message?: string; actor?: string; … }[] ✅ The commit timeline, newest first.

Nested Shape: ListPackageCommitsResponse.commits[number]

Property Type Required Description
id string ✅ Commit id.
operation Enum<'apply' | 'revert'> ✅ Whether the commit applied changes or reverted an earlier commit.
message string optional Commit message, when one was recorded.
actor string optional Who made the commit, when recorded.
aiModel string optional AI model that authored the change, when recorded.
parentCommitId string optional The commit this one chains from, when recorded.
itemCount number ✅ How many items the commit touched.
items { type: string; name: string; member?: string; existedBefore: boolean; … }[] ✅ The items the commit touched.
createdAt string optional When the commit was made (ISO-8601 string), when recorded.

PackageExportManifest

Properties

Property Type Required Description
id string ✅ The exported package's id.
name string ✅ The exported package's machine name.
version string ✅ The exported package's version.
label string optional Display label, when the package declares one.

PackagePublishResult

Properties

Property Type Required Description
success boolean ✅ Whether the publish succeeded
packageId string ✅ The package ID that was published
version integer ✅ New version number after publish
publishedAt string ✅ Publish timestamp
itemsPublished integer ✅ Total metadata items published
validationErrors { type: string; name: string; message: string }[] optional Validation errors if publish failed

Nested Shape: PackagePublishResult.validationErrors[number]

Property Type Required Description
type string ✅ Metadata type that failed validation
name string ✅ Item name that failed validation
message string ✅ Validation error message

ReassignOrphanedMetadataResponse

Properties

Property Type Required Description
success boolean ✅ Whether the reassignment ran.
reassignedCount number ✅ How many orphaned items were adopted.
reassigned { type: string; name: string }[] ✅ Every item that was adopted.
targetPackageId string ✅ The package the items were adopted into.

Nested Shape: ReassignOrphanedMetadataResponse.reassigned[number]

Property Type Required Description
type string ✅ Metadata type of the adopted item.
name string ✅ Name of the adopted item.

RevertPackageCommitResponse

Properties

Property Type Required Description
success boolean ✅ True exactly when nothing failed.
revertedCount number ✅ How many items were reverted.
failedCount number ✅ How many items could not be reverted.
reverted { type: string; name: string; action: Enum<'removed' | 'restored'> }[] ✅ Every item the revert touched.
failed { type: string; name: string; error: string; code?: string }[] ✅ Every item the revert could not touch.
revertCommitId string optional Id of the commit the revert itself created, when one was written.

Nested Shape: RevertPackageCommitResponse.reverted[number]

Property Type Required Description
type string ✅ Metadata type of the reverted item.
name string ✅ Name of the reverted item.
action Enum<'removed' | 'restored'> ✅ What the revert did to the item — removed what the commit created, or restored what it overwrote.

Nested Shape: RevertPackageCommitResponse.failed[number]

Property Type Required Description
type string ✅ Metadata type of the failing item.
name string ✅ Name of the failing item.
error string ✅ Why the revert failed for this item.
code string optional Machine-readable failure code, when one was recorded.

RollbackToPackageCommitResponse

Properties

Property Type Required Description
success boolean ✅ True exactly when nothing failed.
revertedCommits string[] ✅ Ids of the commits that were rolled back, in the order they were reverted.
failed { commitId: string; error: string }[] ✅ Every commit the rollback could not revert.

Nested Shape: RollbackToPackageCommitResponse.failed[number]

Property Type Required Description
commitId string ✅ The commit that could not be reverted.
error string ✅ Why reverting it failed.