ObjectStackPackage Api
Package Api protocol schemas
Package API Protocol
REST API endpoint schemas for package lifecycle management.
Base path: /api/v1/packages
@example Endpoints POST /api/v1/packages/install — Install a package POST /api/v1/packages/upgrade — Upgrade a package POST /api/v1/packages/resolve-dependencies — Resolve dependencies POST /api/v1/packages/upload — Upload an artifact GET /api/v1/packages — List installed packages GET /api/v1/packages/:packageId — Get package details POST /api/v1/packages/:packageId/rollback — Rollback a package DELETE /api/v1/packages/:packageId — Uninstall a package
Source: packages/spec/src/api/package-api.zod.ts
TypeScript Usage
import { GetInstalledPackageRequestSchema, GetInstalledPackageResponseSchema, ListInstalledPackagesRequestSchema, ListInstalledPackagesResponseSchema, PackageApiErrorCode, PackageInstallRequestSchema, PackageInstallResponseSchema, PackagePathParamsSchema, PackageRollbackRequestSchema, PackageRollbackResponseSchema, PackageUpgradeRequestSchema, PackageUpgradeResponseSchema, ResolveDependenciesRequestSchema, ResolveDependenciesResponseSchema, UninstallPackageApiRequestSchema, UninstallPackageApiResponseSchema, UploadArtifactRequestSchema, UploadArtifactResponseSchema } from '@objectstack/spec/api';
import type { GetInstalledPackageRequest, GetInstalledPackageResponse, ListInstalledPackagesRequest, ListInstalledPackagesResponse, PackageApiErrorCode, PackageInstallRequest, PackageInstallResponse, PackagePathParams, PackageRollbackRequest, PackageRollbackResponse, PackageUpgradeRequest, PackageUpgradeResponse, ResolveDependenciesRequest, ResolveDependenciesResponse, UninstallPackageApiRequest, UninstallPackageApiResponse, UploadArtifactRequest, UploadArtifactResponse } from '@objectstack/spec/api';
// Validate data
const result = GetInstalledPackageRequestSchema.parse(data);GetInstalledPackageRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| packageId | string | ✅ | Package identifier |
GetInstalledPackageResponse
Get installed package response
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: number; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { manifest: object; status?: Enum<'installed' | 'disabled' | 'installing' | 'upgrading' | 'uninstalling' | 'error'>; enabled?: boolean; installedAt?: string; … } | ✅ | Installed package details |
ListInstalledPackagesRequest
List installed packages request
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| status | Enum<'installed' | 'disabled' | 'installing' | 'upgrading' | 'uninstalling' | 'error'> | optional | Filter by package status |
| enabled | boolean | optional | Filter by enabled state |
| limit | integer | optional (default: 50) | Maximum number of packages to return |
| cursor | string | optional | Cursor for pagination |
ListInstalledPackagesResponse
List installed packages response
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: number; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { packages: object[]; total?: integer; nextCursor?: string; hasMore: boolean } | ✅ |
PackageApiErrorCode
Allowed Values
package_not_foundpackage_already_installedversion_not_founddependency_conflictnamespace_conflictplatform_incompatibleartifact_invalidchecksum_mismatchsignature_invalidupgrade_failedrollback_failedsnapshot_not_foundupload_failed
PackageInstallRequest
Install package request
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| manifest | { id: string; namespace?: string; defaultDatasource?: string; version: string; … } | ✅ | Package manifest to install |
| settings | Record<string, any> | optional | User-provided settings at install time |
| enableOnInstall | boolean | optional (default: true) | Whether to enable immediately after install |
| platformVersion | string | optional | Current platform version for compatibility verification |
| artifactRef | { url: string; sha256: string; size: integer; format?: Enum<'tgz' | 'zip'>; … } | optional | Artifact reference for marketplace installation |
PackageInstallResponse
Install package response
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: number; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { package: object; dependencyResolution?: object; namespaceConflicts?: object[]; message?: string } | ✅ |
PackagePathParams
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| packageId | string | ✅ | Package identifier |
PackageRollbackRequest
Rollback package request
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| packageId | string | ✅ | Package identifier |
| snapshotId | string | ✅ | Snapshot ID to restore from |
| rollbackCustomizations | boolean | optional (default: true) | Whether to restore pre-upgrade customizations |
PackageRollbackResponse
Rollback package response
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: number; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { success: boolean; restoredVersion?: string; message?: string } | ✅ |
PackageUpgradeRequest
Upgrade package request
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| packageId | string | ✅ | Package ID to upgrade |
| targetVersion | string | optional | Target version (defaults to latest) |
| manifest | { id: string; namespace?: string; defaultDatasource?: string; version: string; … } | optional | New manifest for the target version |
| createSnapshot | boolean | optional (default: true) | Whether to create a pre-upgrade backup snapshot |
| mergeStrategy | Enum<'keep-custom' | 'accept-incoming' | 'three-way-merge'> | optional (default: "three-way-merge") | How to handle customer customizations |
| dryRun | boolean | optional (default: false) | Preview upgrade without making changes |
| skipValidation | boolean | optional (default: false) | Skip pre-upgrade compatibility checks |
PackageUpgradeResponse
Upgrade package response
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: number; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { success: boolean; phase: string; plan?: object; snapshotId?: string; … } | ✅ |
ResolveDependenciesRequest
Resolve dependencies request
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| manifest | { id: string; namespace?: string; defaultDatasource?: string; version: string; … } | ✅ | Package manifest to resolve dependencies for |
| platformVersion | string | optional | Current platform version for compatibility filtering |
ResolveDependenciesResponse
Resolve dependencies response
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: number; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { dependencies: object[]; canProceed: boolean; requiredActions: object[]; installOrder: string[]; … } | ✅ | Dependency resolution result with topological sort |
UninstallPackageApiRequest
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| packageId | string | ✅ | Package identifier |
UninstallPackageApiResponse
Uninstall package response
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: number; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { packageId: string; success: boolean; message?: string } | ✅ |
UploadArtifactRequest
Upload artifact request
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| artifact | { formatVersion: string; packageId: string; version: string; format: Enum<'tgz' | 'zip'>; … } | ✅ | Package artifact metadata |
| sha256 | string | optional | SHA256 checksum of the uploaded file |
| token | string | optional | Publisher authentication token |
| releaseNotes | string | optional | Release notes for this version |
UploadArtifactResponse
Upload artifact response
Properties
| Property | Type | Required | Description |
|---|---|---|---|
| success | boolean | ✅ | Operation success status |
| error | { code: Enum<'VALIDATION_ERROR' | 'INVALID_FIELD' | 'MISSING_REQUIRED_FIELD' | …>; declaredCode?: string; message: string; userMessage?: string; … } | optional | Error details if success is false |
| meta | { timestamp: string; duration?: number; requestId?: string; traceId?: string } | optional | Response metadata |
| data | { success: boolean; artifactRef?: object; submissionId?: string; message?: string } | ✅ |