@evcraddock/slug-api 0.1.1 → 1.0.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -12,4 +12,32 @@ Reusable Hono helpers for Slugkit-compatible management APIs.
12
12
 
13
13
  ## Generated-site ownership
14
14
 
15
- Generated sites should keep local API route modules that compose these helpers with site-owned services, persistence, OpenAPI documents, and route policies. Replace local route modules when a site needs custom API behavior; keep package helpers where shared Slugkit compatibility is useful.
15
+ Generated sites should keep local API route modules that compose these helpers with site-owned services, persistence and route policies; use the packaged official OpenAPI document when adopting its contract. Replace local route modules when a site needs custom API behavior; keep package helpers where shared Slugkit compatibility is useful.
16
+
17
+ ## Official contract
18
+
19
+ `openApiDocument`, `SLUGKIT_CONTRACT_ID`, and `SLUGKIT_CONTRACT_VERSION` export the official management contract. The static `@evcraddock/slug-api/openapi.json` artifact contains the identical document; `@evcraddock/slug-api/contract.json` records its identity, contract version, package version, artifact filename, and SHA-256 digest. Extract these two files from the npm release tarball to publish an archive without installing historical libraries. Each release ships only its own contract. Archive hosting is the responsibility of slugkit.com.
20
+
21
+ Generated sites import this document and pass its identity/version explicitly to `createApiMetaResponse` via `contract`. The `/api/v1/meta` response exposes `api.contract`; the document repeats it in `x-slugkit-contract` and uses the contract version in `info.version`. The legacy `api.version` remains the API routing generation marker and is not evidence of a specific contract.
22
+
23
+ ## Incoming activity contract 2.2.0
24
+
25
+ Package 1.0.0 carries contract 2.2.0. Compared with the previously published contract 1.1.0, following responses replace `contactId` with `accountId`; update clients before adopting the new contract. The source contract's approved 2.1.0 → 2.2.0 minor increment adds boosts to the per-followed-account GET/DELETE buffer. Incoming pages contain `IncomingPost` or `IncomingBoost` without an opt-in filter; existing post payloads and Slug CLI commands remain unchanged. Readers must branch on `kind`, distinguish the followed sharing account from the original author, and handle Account-shaped unsaved-author snapshots with null stored IDs and no permanent Contact creation. Download, explicit removal and reading remain independent; there is no shared-read authority or automatic retention policy. See [Spec 12](https://forge.caradoc.com/erik/slugkit/src/branch/main/docs/specs/12-incoming-activity.md), [isolated evidence](https://forge.caradoc.com/erik/slugkit/src/branch/main/docs/incoming-activity-evidence.md) and [consumer reconciliation](https://forge.caradoc.com/erik/slugkit/src/branch/main/docs/incoming-activity-consumers.md).
26
+
27
+ The API package supplies the shared schema/helpers, not website inbox handlers, storage migrations or deployment. Adopt site-owned changes and migration 030 before claiming implementation support. The package-to-contract mapping is recorded in `contract.json`; verify it and its OpenAPI digest after publication. Publishing these references does not establish that slugkit.com or another deployed website implements the new operations.
28
+
29
+ ## Version and release policy
30
+
31
+ Contract identity is `slugkit-management-api`. Contract `1.1.0` is the first explicitly identified packaged contract; earlier sites reporting `api.version: 1.0.0` may implement different interfaces and must be treated as having an unknown contract.
32
+
33
+ Released contract versions are immutable. Identical documents retain their contract version across helper-only package releases. Every changed document receives a new stable semantic version: documentation-only corrections increment patch, compatible additions increment minor, and breaking changes increment major. Compatible additions include optional fields and new operations that preserve existing requests and responses. Removing operations or fields, changing types or authentication requirements, adding required request inputs, and narrowing accepted values are breaking changes. Reviewers must classify changes; automated checks verify declared release intent and do not establish runtime conformance.
34
+
35
+ Package versions describe the library, including helpers and dependencies. Template versions describe generated-site code. Neither determines a contract version. `contract.json` gives the explicit package-to-contract mapping. A contract change requires a new package release, but several package releases can carry the same contract. Template releases pin the API package they consume.
36
+
37
+ During implementation, edit the contract definition and version constants, select `changeType` (`documentation`, `additive`, or `breaking`) in `contract-release.json`, and update the manifest digest from the formatted JSON output. Keep npm package versions and consumer pins unchanged until explicitly requested release preparation. The development build checks artifact consistency, recorded-version immutability and contract-version compatibility, without demanding a package-version bump. Its generated manifest describes a local build, not a published release or public availability.
38
+
39
+ During release preparation, choose a fresh npm package version, update consumer pins/lockfile and the manifest's `packageVersion`, and run `node scripts/check-api-contract.mjs --release`. This strict check also runs in release preparation validation and both API publishing paths, before npm writes. Changed contract bytes require a new package release. The history guard rejects reuse of a recorded contract version with different bytes in both modes; published contract artifacts remain immutable. Run with full Git history; the release workflow clones full history. The manifest is review evidence, not an independently maintained specification.
40
+
41
+ ## Existing-site adoption
42
+
43
+ Upgrade the API package and compatible core dependency, replace the local OpenAPI definition with the packaged export, and check the site's implemented operations against that document before declaring `api.contract`. Custom sites can continue serving their own document and omit the official declaration. Installing a package or copying metadata alone does not establish conformance. Missing `api.contract` means unknown, including legacy sites advertising `api.version: 1.0.0`; clients must not infer an official contract from template or package metadata. Doctor verification and per-site CLI compatibility are separate work.
@@ -0,0 +1,2 @@
1
+ export declare const SLUGKIT_CONTRACT_ID = "slugkit-management-api";
2
+ export declare const SLUGKIT_CONTRACT_VERSION = "2.2.0";
@@ -0,0 +1,2 @@
1
+ export const SLUGKIT_CONTRACT_ID = "slugkit-management-api";
2
+ export const SLUGKIT_CONTRACT_VERSION = "2.2.0";
@@ -0,0 +1,9 @@
1
+ {
2
+ "id": "slugkit-management-api",
3
+ "version": "2.2.0",
4
+ "packageName": "@evcraddock/slug-api",
5
+ "packageVersion": "1.0.0",
6
+ "artifact": "openapi.json",
7
+ "sha256": "183e57ea59d2e37f9ea862940a94f38966b2c418d244ee9ff8f355bac1986925",
8
+ "changeType": "additive"
9
+ }
package/dist/index.d.ts CHANGED
@@ -1,11 +1,14 @@
1
+ export { SLUGKIT_CONTRACT_ID, SLUGKIT_CONTRACT_VERSION } from "./contract.js";
2
+ export { openApiDocument } from "./openapi.js";
1
3
  import type { Context, Hono, MiddlewareHandler } from "hono";
2
- import { type CreateSlugkitErrorInput, type SlugkitError, type SlugkitErrorCode, type SlugkitErrorResponse, type SlugkitFieldError, type SlugkitMetaResponse, type SlugkitPackageMetadata, type SlugkitSuccessResponse } from "@evcraddock/slug-core";
4
+ import { type CreateSlugkitErrorInput, type SlugkitError, type SlugkitErrorCode, type SlugkitErrorResponse, type SlugkitFieldError, type SlugkitMetaResponse, type SlugkitContractMetadata, type SlugkitPackageMetadata, type SlugkitSuccessResponse } from "@evcraddock/slug-core";
3
5
  export type ApiErrorCode = SlugkitErrorCode;
4
6
  export type ApiFieldError = SlugkitFieldError;
5
7
  export type ApiError = SlugkitError;
6
8
  export type ApiErrorResponse = SlugkitErrorResponse;
7
9
  export type ApiSuccessResponse<TData> = SlugkitSuccessResponse<TData>;
8
10
  export type ApiMetaResponse = SlugkitMetaResponse;
11
+ export type ApiContractMetadata = SlugkitContractMetadata;
9
12
  export interface ApiHealthResponse {
10
13
  status: "ok";
11
14
  service: "slugkit-api";
@@ -22,6 +25,7 @@ export interface ApiMetaInput {
22
25
  softwareVersion: string;
23
26
  softwareName?: string;
24
27
  packageMetadata?: SlugkitPackageMetadata;
28
+ contract?: ApiContractMetadata;
25
29
  }
26
30
  export type BearerTokenValidator = (token: string, operation: string, method: string) => boolean | Promise<boolean>;
27
31
  export interface BearerAuthOptions {
@@ -59,4 +63,3 @@ export declare function registerHealthRoute(app: Hono, options: RegisterHealthRo
59
63
  export declare function registerMetaRoute(app: Hono, options: RegisterMetaRouteOptions): void;
60
64
  export declare function serveOpenApiDocument(context: Context, document: unknown): Response;
61
65
  export declare function registerOpenApiDocumentRoute(app: Hono, options: RegisterOpenApiDocumentRouteOptions): void;
62
- export {};
package/dist/index.js CHANGED
@@ -1,3 +1,5 @@
1
+ export { SLUGKIT_CONTRACT_ID, SLUGKIT_CONTRACT_VERSION } from "./contract.js";
2
+ export { openApiDocument } from "./openapi.js";
1
3
  import { createSlugkitErrorResponse, createSlugkitSuccessResponse, SLUGKIT_API_BASE_PATH, SLUGKIT_API_NAME, SLUGKIT_API_VERSION, SLUGKIT_OPENAPI_PATH, SLUGKIT_TEMPLATE_SOFTWARE_NAME, } from "@evcraddock/slug-core";
2
4
  export function createSuccessResponse(data) {
3
5
  return createSlugkitSuccessResponse(data);
@@ -74,6 +76,9 @@ export function createApiMetaResponse(input) {
74
76
  version: input.softwareVersion,
75
77
  },
76
78
  };
79
+ if (input.contract !== undefined) {
80
+ response.api.contract = input.contract;
81
+ }
77
82
  if (input.packageMetadata !== undefined) {
78
83
  response.packageMetadata = input.packageMetadata;
79
84
  }