@evcraddock/slug-api 0.1.0 → 0.2.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 +21 -1
- package/dist/contract.d.ts +2 -0
- package/dist/contract.js +2 -0
- package/dist/contract.json +9 -0
- package/dist/index.d.ts +6 -2
- package/dist/index.js +10 -1
- package/dist/openapi.d.ts +4254 -0
- package/dist/openapi.js +2019 -0
- package/dist/openapi.json +5106 -0
- package/package.json +6 -4
package/README.md
CHANGED
|
@@ -12,4 +12,24 @@ 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
|
|
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
|
+
## Version and release policy
|
|
24
|
+
|
|
25
|
+
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.
|
|
26
|
+
|
|
27
|
+
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.
|
|
28
|
+
|
|
29
|
+
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.
|
|
30
|
+
|
|
31
|
+
To change a contract, edit the package definition and version constants, select `changeType` (`documentation`, `additive`, or `breaking`) in `contract-release.json`, update the package version and consumer pins, then update the manifest digest from the formatted JSON output. The build verifies the manifest against the exported document and generates static artifacts. The history guard rejects reuse of an existing version with a different digest and verifies the version bump against the declared change type. Run with full Git history for release validation; the repository release workflow clones full history. The manifest is review evidence, not an independently maintained specification.
|
|
32
|
+
|
|
33
|
+
## Existing-site adoption
|
|
34
|
+
|
|
35
|
+
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.
|
package/dist/contract.js
ADDED
|
@@ -0,0 +1,9 @@
|
|
|
1
|
+
{
|
|
2
|
+
"id": "slugkit-management-api",
|
|
3
|
+
"version": "1.1.0",
|
|
4
|
+
"packageName": "@evcraddock/slug-api",
|
|
5
|
+
"packageVersion": "0.2.0",
|
|
6
|
+
"artifact": "openapi.json",
|
|
7
|
+
"sha256": "7ce649806998cee82432e60617685886088416b07a8a9b8df3e0721abcd3b37b",
|
|
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 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";
|
|
@@ -21,6 +24,8 @@ export interface ApiMetaInput {
|
|
|
21
24
|
site: SiteMetadataInput;
|
|
22
25
|
softwareVersion: string;
|
|
23
26
|
softwareName?: string;
|
|
27
|
+
packageMetadata?: SlugkitPackageMetadata;
|
|
28
|
+
contract?: ApiContractMetadata;
|
|
24
29
|
}
|
|
25
30
|
export type BearerTokenValidator = (token: string, operation: string, method: string) => boolean | Promise<boolean>;
|
|
26
31
|
export interface BearerAuthOptions {
|
|
@@ -58,4 +63,3 @@ export declare function registerHealthRoute(app: Hono, options: RegisterHealthRo
|
|
|
58
63
|
export declare function registerMetaRoute(app: Hono, options: RegisterMetaRouteOptions): void;
|
|
59
64
|
export declare function serveOpenApiDocument(context: Context, document: unknown): Response;
|
|
60
65
|
export declare function registerOpenApiDocumentRoute(app: Hono, options: RegisterOpenApiDocumentRouteOptions): void;
|
|
61
|
-
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);
|
|
@@ -58,7 +60,7 @@ export function createApiHealthResponse(input) {
|
|
|
58
60
|
export function createApiMetaResponse(input) {
|
|
59
61
|
const origin = new URL(input.requestUrl).origin;
|
|
60
62
|
const baseUrl = `${origin}${SLUGKIT_API_BASE_PATH}`;
|
|
61
|
-
|
|
63
|
+
const response = {
|
|
62
64
|
site: {
|
|
63
65
|
name: input.site.name,
|
|
64
66
|
url: input.site.url,
|
|
@@ -74,6 +76,13 @@ 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
|
+
}
|
|
82
|
+
if (input.packageMetadata !== undefined) {
|
|
83
|
+
response.packageMetadata = input.packageMetadata;
|
|
84
|
+
}
|
|
85
|
+
return response;
|
|
77
86
|
}
|
|
78
87
|
export function readBearerToken(context) {
|
|
79
88
|
const authorization = context.req.header("authorization");
|