@evcraddock/slug-api 0.1.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 +15 -0
- package/dist/index.d.ts +61 -0
- package/dist/index.js +114 -0
- package/package.json +36 -0
package/README.md
ADDED
|
@@ -0,0 +1,15 @@
|
|
|
1
|
+
# @evcraddock/slug-api
|
|
2
|
+
|
|
3
|
+
Reusable Hono helpers for Slugkit-compatible management APIs.
|
|
4
|
+
|
|
5
|
+
## Exports
|
|
6
|
+
|
|
7
|
+
- Response helpers: `createSuccessResponse`, `createJsonResponse`, `createErrorResponse`, `createValidationErrorResponse`, `createNotFoundErrorResponse`, `createConflictErrorResponse`, `createAuthenticationErrorResponse`, `createNotImplementedErrorResponse`, and `createNotImplementedResponse`.
|
|
8
|
+
- Metadata helpers: `createApiHealthResponse` and `createApiMetaResponse`.
|
|
9
|
+
- Bearer auth helpers: `readBearerToken`, `createBearerAuthMiddleware`, `BearerTokenValidator`, and `BearerAuthOptions`.
|
|
10
|
+
- Route helpers: `registerHealthRoute`, `registerMetaRoute`, `serveOpenApiDocument`, and `registerOpenApiDocumentRoute`.
|
|
11
|
+
- API response and metadata types re-exported from Slugkit core shapes.
|
|
12
|
+
|
|
13
|
+
## Generated-site ownership
|
|
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.
|
package/dist/index.d.ts
ADDED
|
@@ -0,0 +1,61 @@
|
|
|
1
|
+
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";
|
|
3
|
+
export type ApiErrorCode = SlugkitErrorCode;
|
|
4
|
+
export type ApiFieldError = SlugkitFieldError;
|
|
5
|
+
export type ApiError = SlugkitError;
|
|
6
|
+
export type ApiErrorResponse = SlugkitErrorResponse;
|
|
7
|
+
export type ApiSuccessResponse<TData> = SlugkitSuccessResponse<TData>;
|
|
8
|
+
export type ApiMetaResponse = SlugkitMetaResponse;
|
|
9
|
+
export interface ApiHealthResponse {
|
|
10
|
+
status: "ok";
|
|
11
|
+
service: "slugkit-api";
|
|
12
|
+
version: string;
|
|
13
|
+
time: string;
|
|
14
|
+
}
|
|
15
|
+
export interface SiteMetadataInput {
|
|
16
|
+
name: string;
|
|
17
|
+
url: string;
|
|
18
|
+
}
|
|
19
|
+
export interface ApiMetaInput {
|
|
20
|
+
requestUrl: string;
|
|
21
|
+
site: SiteMetadataInput;
|
|
22
|
+
softwareVersion: string;
|
|
23
|
+
softwareName?: string;
|
|
24
|
+
}
|
|
25
|
+
export type BearerTokenValidator = (token: string, operation: string, method: string) => boolean | Promise<boolean>;
|
|
26
|
+
export interface BearerAuthOptions {
|
|
27
|
+
operation: string;
|
|
28
|
+
validateToken: BearerTokenValidator;
|
|
29
|
+
}
|
|
30
|
+
export interface RegisterHealthRouteOptions {
|
|
31
|
+
getVersion: () => string;
|
|
32
|
+
now?: () => Date;
|
|
33
|
+
}
|
|
34
|
+
export interface RegisterMetaRouteOptions {
|
|
35
|
+
readMeta: (context: Context) => ApiMetaResponse;
|
|
36
|
+
}
|
|
37
|
+
export interface RegisterOpenApiDocumentRouteOptions {
|
|
38
|
+
document: unknown;
|
|
39
|
+
}
|
|
40
|
+
type ErrorResponseInput = CreateSlugkitErrorInput;
|
|
41
|
+
export declare function createSuccessResponse<TData>(data: TData): ApiSuccessResponse<TData>;
|
|
42
|
+
export declare function createJsonResponse<TData>(data: TData): ApiSuccessResponse<TData>;
|
|
43
|
+
export declare function createErrorResponse(input: ErrorResponseInput): ApiErrorResponse;
|
|
44
|
+
export declare function createValidationErrorResponse(operation: string, fields: ApiFieldError[], message?: string): ApiErrorResponse;
|
|
45
|
+
export declare function createNotFoundErrorResponse(operation: string, message?: string): ApiErrorResponse;
|
|
46
|
+
export declare function createConflictErrorResponse(operation: string, message?: string): ApiErrorResponse;
|
|
47
|
+
export declare function createAuthenticationErrorResponse(operation: string, message?: string): ApiErrorResponse;
|
|
48
|
+
export declare function createNotImplementedErrorResponse(operation: string): ApiErrorResponse;
|
|
49
|
+
export declare function createNotImplementedResponse(operation: string): ApiErrorResponse;
|
|
50
|
+
export declare function createApiHealthResponse(input: {
|
|
51
|
+
version: string;
|
|
52
|
+
now?: Date;
|
|
53
|
+
}): ApiHealthResponse;
|
|
54
|
+
export declare function createApiMetaResponse(input: ApiMetaInput): ApiMetaResponse;
|
|
55
|
+
export declare function readBearerToken(context: Context): string | null;
|
|
56
|
+
export declare function createBearerAuthMiddleware(options: BearerAuthOptions): MiddlewareHandler;
|
|
57
|
+
export declare function registerHealthRoute(app: Hono, options: RegisterHealthRouteOptions): void;
|
|
58
|
+
export declare function registerMetaRoute(app: Hono, options: RegisterMetaRouteOptions): void;
|
|
59
|
+
export declare function serveOpenApiDocument(context: Context, document: unknown): Response;
|
|
60
|
+
export declare function registerOpenApiDocumentRoute(app: Hono, options: RegisterOpenApiDocumentRouteOptions): void;
|
|
61
|
+
export {};
|
package/dist/index.js
ADDED
|
@@ -0,0 +1,114 @@
|
|
|
1
|
+
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
|
+
export function createSuccessResponse(data) {
|
|
3
|
+
return createSlugkitSuccessResponse(data);
|
|
4
|
+
}
|
|
5
|
+
export function createJsonResponse(data) {
|
|
6
|
+
return createSuccessResponse(data);
|
|
7
|
+
}
|
|
8
|
+
export function createErrorResponse(input) {
|
|
9
|
+
return createSlugkitErrorResponse(input);
|
|
10
|
+
}
|
|
11
|
+
export function createValidationErrorResponse(operation, fields, message = "Validation failed") {
|
|
12
|
+
return createErrorResponse({
|
|
13
|
+
code: "VALIDATION_ERROR",
|
|
14
|
+
message,
|
|
15
|
+
operation,
|
|
16
|
+
fields,
|
|
17
|
+
});
|
|
18
|
+
}
|
|
19
|
+
export function createNotFoundErrorResponse(operation, message = "Resource not found") {
|
|
20
|
+
return createErrorResponse({
|
|
21
|
+
code: "NOT_FOUND",
|
|
22
|
+
message,
|
|
23
|
+
operation,
|
|
24
|
+
});
|
|
25
|
+
}
|
|
26
|
+
export function createConflictErrorResponse(operation, message = "Resource conflict") {
|
|
27
|
+
return createErrorResponse({
|
|
28
|
+
code: "CONFLICT",
|
|
29
|
+
message,
|
|
30
|
+
operation,
|
|
31
|
+
});
|
|
32
|
+
}
|
|
33
|
+
export function createAuthenticationErrorResponse(operation, message = "Authentication required") {
|
|
34
|
+
return createErrorResponse({
|
|
35
|
+
code: "AUTHENTICATION_ERROR",
|
|
36
|
+
message,
|
|
37
|
+
operation,
|
|
38
|
+
});
|
|
39
|
+
}
|
|
40
|
+
export function createNotImplementedErrorResponse(operation) {
|
|
41
|
+
return createErrorResponse({
|
|
42
|
+
code: "NOT_IMPLEMENTED",
|
|
43
|
+
message: "This site does not implement this operation.",
|
|
44
|
+
operation,
|
|
45
|
+
});
|
|
46
|
+
}
|
|
47
|
+
export function createNotImplementedResponse(operation) {
|
|
48
|
+
return createNotImplementedErrorResponse(operation);
|
|
49
|
+
}
|
|
50
|
+
export function createApiHealthResponse(input) {
|
|
51
|
+
return {
|
|
52
|
+
status: "ok",
|
|
53
|
+
service: "slugkit-api",
|
|
54
|
+
version: input.version,
|
|
55
|
+
time: (input.now ?? new Date()).toISOString(),
|
|
56
|
+
};
|
|
57
|
+
}
|
|
58
|
+
export function createApiMetaResponse(input) {
|
|
59
|
+
const origin = new URL(input.requestUrl).origin;
|
|
60
|
+
const baseUrl = `${origin}${SLUGKIT_API_BASE_PATH}`;
|
|
61
|
+
return {
|
|
62
|
+
site: {
|
|
63
|
+
name: input.site.name,
|
|
64
|
+
url: input.site.url,
|
|
65
|
+
},
|
|
66
|
+
api: {
|
|
67
|
+
name: SLUGKIT_API_NAME,
|
|
68
|
+
version: SLUGKIT_API_VERSION,
|
|
69
|
+
baseUrl,
|
|
70
|
+
openapiUrl: `${baseUrl}${SLUGKIT_OPENAPI_PATH}`,
|
|
71
|
+
},
|
|
72
|
+
software: {
|
|
73
|
+
name: input.softwareName ?? SLUGKIT_TEMPLATE_SOFTWARE_NAME,
|
|
74
|
+
version: input.softwareVersion,
|
|
75
|
+
},
|
|
76
|
+
};
|
|
77
|
+
}
|
|
78
|
+
export function readBearerToken(context) {
|
|
79
|
+
const authorization = context.req.header("authorization");
|
|
80
|
+
if (authorization === undefined) {
|
|
81
|
+
return null;
|
|
82
|
+
}
|
|
83
|
+
const [scheme, token] = authorization.split(" ", 2);
|
|
84
|
+
if (scheme !== "Bearer" || token === undefined || token.trim() === "") {
|
|
85
|
+
return null;
|
|
86
|
+
}
|
|
87
|
+
return token;
|
|
88
|
+
}
|
|
89
|
+
export function createBearerAuthMiddleware(options) {
|
|
90
|
+
return async (context, next) => {
|
|
91
|
+
const token = readBearerToken(context);
|
|
92
|
+
if (token === null ||
|
|
93
|
+
!(await options.validateToken(token, options.operation, context.req.method))) {
|
|
94
|
+
return context.json(createAuthenticationErrorResponse(options.operation), 401);
|
|
95
|
+
}
|
|
96
|
+
await next();
|
|
97
|
+
};
|
|
98
|
+
}
|
|
99
|
+
export function registerHealthRoute(app, options) {
|
|
100
|
+
app.get("/health", (context) => {
|
|
101
|
+
return context.json(createApiHealthResponse({ version: options.getVersion(), now: options.now?.() }));
|
|
102
|
+
});
|
|
103
|
+
}
|
|
104
|
+
export function registerMetaRoute(app, options) {
|
|
105
|
+
app.get("/meta", (context) => {
|
|
106
|
+
return context.json(options.readMeta(context));
|
|
107
|
+
});
|
|
108
|
+
}
|
|
109
|
+
export function serveOpenApiDocument(context, document) {
|
|
110
|
+
return context.json(document);
|
|
111
|
+
}
|
|
112
|
+
export function registerOpenApiDocumentRoute(app, options) {
|
|
113
|
+
app.get("/openapi.json", (context) => serveOpenApiDocument(context, options.document));
|
|
114
|
+
}
|
package/package.json
ADDED
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
{
|
|
2
|
+
"name": "@evcraddock/slug-api",
|
|
3
|
+
"version": "0.1.0",
|
|
4
|
+
"description": "Reusable Hono helpers for Slugkit-compatible management APIs.",
|
|
5
|
+
"license": "MIT",
|
|
6
|
+
"private": false,
|
|
7
|
+
"type": "module",
|
|
8
|
+
"exports": {
|
|
9
|
+
".": {
|
|
10
|
+
"types": "./dist/index.d.ts",
|
|
11
|
+
"default": "./dist/index.js"
|
|
12
|
+
}
|
|
13
|
+
},
|
|
14
|
+
"files": [
|
|
15
|
+
"dist",
|
|
16
|
+
"README.md",
|
|
17
|
+
"package.json"
|
|
18
|
+
],
|
|
19
|
+
"publishConfig": {
|
|
20
|
+
"access": "public"
|
|
21
|
+
},
|
|
22
|
+
"scripts": {
|
|
23
|
+
"build": "tsc -p tsconfig.build.json",
|
|
24
|
+
"typecheck": "tsc --noEmit -p tsconfig.json",
|
|
25
|
+
"test": "vitest run --config ../../vitest.config.ts src",
|
|
26
|
+
"test:watch": "vitest --config ../../vitest.config.ts src"
|
|
27
|
+
},
|
|
28
|
+
"dependencies": {
|
|
29
|
+
"@evcraddock/slug-core": "0.1.0",
|
|
30
|
+
"hono": "^4.12.23"
|
|
31
|
+
},
|
|
32
|
+
"devDependencies": {
|
|
33
|
+
"typescript": "5.9.3",
|
|
34
|
+
"vitest": "4.1.6"
|
|
35
|
+
}
|
|
36
|
+
}
|