vintasend-api 0.0.0-stage → 1.0.0-alpha6

package/dist/index.d.ts

@@ -0,0 +1,8 @@
+#!/usr/bin/env node
+/**
+ * Server entrypoint: wires environment configuration into the app and listens.
+ *
+ * Installed as the package's `vintasend-api` command, for running the API on its own. A host that
+ * already has a server mounts `createApp` instead and never loads this file.
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+/**
+ * Server entrypoint: wires environment configuration into the app and listens.
+ *
+ * Installed as the package's `vintasend-api` command, for running the API on its own. A host that
+ * already has a server mounts `createApp` instead and never loads this file.
+ */
+import { serve } from '@hono/node-server';
+import { createApp } from './app.js';
+import { loadServerConfig } from './config.js';
+import { apiKeyAuthenticator } from './middleware/authenticate.js';
+import { createGitHubTemplateClientFromEnv } from './services/github-template-client.js';
+import { createServiceProvider } from './services/service-loader.js';
+async function main() {
+    const config = loadServerConfig();
+    const getService = createServiceProvider(config.serviceModule);
+    const app = createApp({
+        authenticate: apiKeyAuthenticator(config.apiKey),
+        getService,
+        getTemplateClient: () => createGitHubTemplateClientFromEnv(),
+        backendIdentifier: config.backendIdentifier,
+        corsOrigins: config.corsOrigins,
+    });
+    // Fail fast on a broken service module instead of surfacing it per request.
+    await getService();
+    serve({ fetch: app.fetch, port: config.port, hostname: config.host }, (info) => {
+        console.info(`[vintasend-api] listening on http://${config.host}:${info.port}`);
+    });
+}
+main().catch((error) => {
+    console.error('[vintasend-api] failed to start', error);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AACA;;;;;GAKG;AAEH,OAAO,EAAE,KAAK,EAAE,MAAM,mBAAmB,CAAC;AAE1C,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,OAAO,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,mBAAmB,EAAE,MAAM,8BAA8B,CAAC;AACnE,OAAO,EAAE,iCAAiC,EAAE,MAAM,sCAAsC,CAAC;AACzF,OAAO,EAAE,qBAAqB,EAAE,MAAM,8BAA8B,CAAC;AAErE,KAAK,UAAU,IAAI;IACjB,MAAM,MAAM,GAAG,gBAAgB,EAAE,CAAC;IAClC,MAAM,UAAU,GAAG,qBAAqB,CAAC,MAAM,CAAC,aAAa,CAAC,CAAC;IAE/D,MAAM,GAAG,GAAG,SAAS,CAAC;QACpB,YAAY,EAAE,mBAAmB,CAAC,MAAM,CAAC,MAAM,CAAC;QAChD,UAAU;QACV,iBAAiB,EAAE,GAAG,EAAE,CAAC,iCAAiC,EAAE;QAC5D,iBAAiB,EAAE,MAAM,CAAC,iBAAiB;QAC3C,WAAW,EAAE,MAAM,CAAC,WAAW;KAChC,CAAC,CAAC;IAEH,4EAA4E;IAC5E,MAAM,UAAU,EAAE,CAAC;IAEnB,KAAK,CAAC,EAAE,KAAK,EAAE,GAAG,CAAC,KAAK,EAAE,IAAI,EAAE,MAAM,CAAC,IAAI,EAAE,QAAQ,EAAE,MAAM,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,EAAE,EAAE;QAC7E,OAAO,CAAC,IAAI,CAAC,uCAAuC,MAAM,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC,CAAC;IAClF,CAAC,CAAC,CAAC;AACL,CAAC;AAED,IAAI,EAAE,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;IACrB,OAAO,CAAC,KAAK,CAAC,iCAAiC,EAAE,KAAK,CAAC,CAAC;IACxD,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC;AAClB,CAAC,CAAC,CAAC"}

package/dist/middleware/authenticate.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Who is calling, and whether they may.
+ *
+ * Every `/api/v1` request goes through one `Authenticator` before it reaches a route. It refuses a
+ * caller by throwing — `ApiError.unauthorized` when no valid credential was presented,
+ * `ApiError.forbidden` when it knows who the caller is and they may not do this.
+ *
+ * The type is the one `vintasend-templates-management-api` takes, so a host mounting both APIs
+ * passes them the same function. This API records no attribution, so an `actor` it returns is
+ * available to the routes through `authenticated(c)` but nothing here writes it anywhere.
+ *
+ * A host that authenticates its own users passes an authenticator reading its session. A
+ * deployment with one shared secret passes `apiKeyAuthenticator(key)`.
+ */
+import type { Context, MiddlewareHandler } from 'hono';
+/** What an authenticator learned about the caller. */
+export type Authenticated = {
+    /**
+     * Who is calling, when the credential says. The templates management API records it on status
+     * changes; this one keeps no audit trail, so it is accepted and unused.
+     */
+    actor?: string | null;
+};
+/** Refuses the caller by throwing an `ApiError`, or says who they are. */
+export type Authenticator = (c: Context) => Authenticated | Promise<Authenticated>;
+/** Runs `authenticate` on every request it guards, and keeps what it learned for the routes. */
+export declare function authenticateWith(authenticate: Authenticator): MiddlewareHandler;
+/** What the authenticator learned about this request's caller. */
+export declare function authenticated(c: Context): Authenticated;
+/**
+ * The shared-secret authenticator: every request must carry `Authorization: Bearer <apiKey>`.
+ * It says nothing about who is calling.
+ */
+export declare function apiKeyAuthenticator(apiKey: string): Authenticator;

package/dist/middleware/authenticate.js

@@ -0,0 +1,68 @@
+/**
+ * Who is calling, and whether they may.
+ *
+ * Every `/api/v1` request goes through one `Authenticator` before it reaches a route. It refuses a
+ * caller by throwing — `ApiError.unauthorized` when no valid credential was presented,
+ * `ApiError.forbidden` when it knows who the caller is and they may not do this.
+ *
+ * The type is the one `vintasend-templates-management-api` takes, so a host mounting both APIs
+ * passes them the same function. This API records no attribution, so an `actor` it returns is
+ * available to the routes through `authenticated(c)` but nothing here writes it anywhere.
+ *
+ * A host that authenticates its own users passes an authenticator reading its session. A
+ * deployment with one shared secret passes `apiKeyAuthenticator(key)`.
+ */
+import { ApiError } from '../errors.js';
+const AUTHENTICATED = 'vintasend-templates-management-api.authenticated';
+/** Runs `authenticate` on every request it guards, and keeps what it learned for the routes. */
+export function authenticateWith(authenticate) {
+    return async (c, next) => {
+        c.set(AUTHENTICATED, await authenticate(c));
+        await next();
+    };
+}
+/** What the authenticator learned about this request's caller. */
+export function authenticated(c) {
+    return c.get(AUTHENTICATED) ?? {};
+}
+const encoder = new TextEncoder();
+async function sha256(value) {
+    return new Uint8Array(await crypto.subtle.digest('SHA-256', encoder.encode(value)));
+}
+/**
+ * Compare two secrets in time that depends on neither, so a wrong key cannot be found one
+ * character at a time.
+ *
+ * Both are hashed first, so the comparison is always of two 32-byte digests and the length of the
+ * expected key does not leak either. Web Crypto rather than `node:crypto`, so the app runs
+ * wherever `fetch` does.
+ */
+async function safeEquals(a, b) {
+    const [left, right] = await Promise.all([sha256(a), sha256(b)]);
+    let difference = 0;
+    left.forEach((byte, index) => {
+        difference |= byte ^ (right[index] ?? 0);
+    });
+    return difference === 0;
+}
+function extractToken(header) {
+    if (!header) {
+        return undefined;
+    }
+    const match = header.match(/^Bearer\s+(.+)$/i);
+    return match?.[1]?.trim();
+}
+/**
+ * The shared-secret authenticator: every request must carry `Authorization: Bearer <apiKey>`.
+ * It says nothing about who is calling.
+ */
+export function apiKeyAuthenticator(apiKey) {
+    return async (c) => {
+        const token = extractToken(c.req.header('authorization'));
+        if (!token || !(await safeEquals(token, apiKey))) {
+            throw ApiError.unauthorized('A valid API key is required.');
+        }
+        return {};
+    };
+}
+//# sourceMappingURL=authenticate.js.map

package/dist/middleware/authenticate.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"authenticate.js","sourceRoot":"","sources":["../../src/middleware/authenticate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;GAaG;AAIH,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAcxC,MAAM,aAAa,GAAG,kDAAkD,CAAC;AAEzE,gGAAgG;AAChG,MAAM,UAAU,gBAAgB,CAAC,YAA2B;IAC1D,OAAO,KAAK,EAAE,CAAC,EAAE,IAAI,EAAE,EAAE;QACvB,CAAC,CAAC,GAAG,CAAC,aAAa,EAAE,MAAM,YAAY,CAAC,CAAC,CAAC,CAAC,CAAC;QAC5C,MAAM,IAAI,EAAE,CAAC;IACf,CAAC,CAAC;AACJ,CAAC;AAED,kEAAkE;AAClE,MAAM,UAAU,aAAa,CAAC,CAAU;IACtC,OAAQ,CAAC,CAAC,GAAG,CAAC,aAAa,CAA+B,IAAI,EAAE,CAAC;AACnE,CAAC;AAED,MAAM,OAAO,GAAG,IAAI,WAAW,EAAE,CAAC;AAElC,KAAK,UAAU,MAAM,CAAC,KAAa;IACjC,OAAO,IAAI,UAAU,CAAC,MAAM,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,SAAS,EAAE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;AACtF,CAAC;AAED;;;;;;;GAOG;AACH,KAAK,UAAU,UAAU,CAAC,CAAS,EAAE,CAAS;IAC5C,MAAM,CAAC,IAAI,EAAE,KAAK,CAAC,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC;IAChE,IAAI,UAAU,GAAG,CAAC,CAAC;IACnB,IAAI,CAAC,OAAO,CAAC,CAAC,IAAI,EAAE,KAAK,EAAE,EAAE;QAC3B,UAAU,IAAI,IAAI,GAAG,CAAC,KAAK,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC,CAAC;IAC3C,CAAC,CAAC,CAAC;IACH,OAAO,UAAU,KAAK,CAAC,CAAC;AAC1B,CAAC;AAED,SAAS,YAAY,CAAC,MAA0B;IAC9C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,OAAO,SAAS,CAAC;IACnB,CAAC;IAED,MAAM,KAAK,GAAG,MAAM,CAAC,KAAK,CAAC,kBAAkB,CAAC,CAAC;IAC/C,OAAO,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,CAAC;AAC5B,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,mBAAmB,CAAC,MAAc;IAChD,OAAO,KAAK,EAAE,CAAC,EAAE,EAAE;QACjB,MAAM,KAAK,GAAG,YAAY,CAAC,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,eAAe,CAAC,CAAC,CAAC;QAE1D,IAAI,CAAC,KAAK,IAAI,CAAC,CAAC,MAAM,UAAU,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC,EAAE,CAAC;YACjD,MAAM,QAAQ,CAAC,YAAY,CAAC,8BAA8B,CAAC,CAAC;QAC9D,CAAC;QAED,OAAO,EAAE,CAAC;IACZ,CAAC,CAAC;AACJ,CAAC"}

package/dist/middleware/error-handler.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Maps thrown errors to the contract's error envelope.
+ *
+ * Unexpected errors are reported generically, so backend internals never leak to a client. They
+ * are not logged whole either: an error from a notification backend or provider can quote
+ * notification content, recipients or context values, and the applications this API serves
+ * handle health data. The default log line names the error, a request id and the route, nothing
+ * else. A host that wants more — an error tracker with its own scrubbing, say — injects
+ * `onUnhandledError`.
+ */
+import type { Context, ErrorHandler } from 'hono';
+/**
+ * Receives every error the API does not map to a contract error, before the generic 500 is sent.
+ *
+ * It is handed the error object itself, so whatever it does with it is the host's call — and the
+ * host's responsibility to keep health data out of its logs. `requestId` is the id the 500
+ * response carries in its `X-Request-Id` header, for matching a client's report to the log.
+ */
+export type UnhandledErrorHandler = (error: Error, c: Context, details: {
+    requestId: string;
+}) => void | Promise<void>;
+export declare const REQUEST_ID_HEADER = "x-request-id";
+/** The caller's `X-Request-Id` when it is safe to log, otherwise a fresh one. */
+export declare function requestIdFor(c: Context): string;
+/**
+ * The default `onUnhandledError`: one line with the error's name, the request id and the matched
+ * route pattern — never the error's message, its stack, or the request.
+ *
+ * `name` rather than the constructor's name: some backends' errors come from minified bundles.
+ */
+export declare function logUnhandledError(error: Error, c: Context, { requestId }: {
+    requestId: string;
+}): void;
+export declare function createErrorHandler(onUnhandledError?: UnhandledErrorHandler): ErrorHandler;
+export declare function handleNotFound(c: Context): Response;

package/dist/middleware/error-handler.js

@@ -0,0 +1,89 @@
+/**
+ * Maps thrown errors to the contract's error envelope.
+ *
+ * Unexpected errors are reported generically, so backend internals never leak to a client. They
+ * are not logged whole either: an error from a notification backend or provider can quote
+ * notification content, recipients or context values, and the applications this API serves
+ * handle health data. The default log line names the error, a request id and the route, nothing
+ * else. A host that wants more — an error tracker with its own scrubbing, say — injects
+ * `onUnhandledError`.
+ */
+import { HTTPException } from 'hono/http-exception';
+import { asApiError, invalidRequest } from '../errors.js';
+export const REQUEST_ID_HEADER = 'x-request-id';
+/** Only a request id that cannot break a log line out of its field is taken from the client. */
+const SAFE_REQUEST_ID = /^[A-Za-z0-9._-]{1,128}$/;
+/** The caller's `X-Request-Id` when it is safe to log, otherwise a fresh one. */
+export function requestIdFor(c) {
+    const supplied = c.req.header(REQUEST_ID_HEADER);
+    return supplied !== undefined && SAFE_REQUEST_ID.test(supplied) ? supplied : crypto.randomUUID();
+}
+/**
+ * The default `onUnhandledError`: one line with the error's name, the request id and the matched
+ * route pattern — never the error's message, its stack, or the request.
+ *
+ * `name` rather than the constructor's name: some backends' errors come from minified bundles.
+ */
+export function logUnhandledError(error, c, { requestId }) {
+    console.error(`[vintasend-api] unhandled ${error.name || 'Error'} (request ${requestId}) on ` +
+        `${c.req.method} ${c.req.routePath}`);
+}
+/**
+ * Hand `error` to the configured handler, falling back to `logUnhandledError` if it throws.
+ *
+ * What the handler threw is never logged — it is no safer than the error it was handling — and a
+ * broken logging setup must not turn a 500 into a crash.
+ */
+async function reportUnhandledError(handler, error, c, requestId) {
+    try {
+        await handler(error, c, { requestId });
+        return;
+    }
+    catch {
+        // Fall through to the default line.
+    }
+    if (handler === logUnhandledError) {
+        return;
+    }
+    try {
+        logUnhandledError(error, c, { requestId });
+    }
+    catch {
+        // Nothing left to report to.
+    }
+}
+export function createErrorHandler(onUnhandledError = logUnhandledError) {
+    return async (error, c) => {
+        const contractError = asApiError(error);
+        if (contractError !== undefined) {
+            return c.json(contractError.toResponseBody(), contractError.status);
+        }
+        // Hono's validator refusing a body that declares JSON and is not: empty, or malformed. It is
+        // invalid input like any other, so it gets the same `details.issues`.
+        if (error instanceof HTTPException && error.status === 400) {
+            const refusal = invalidRequest([{ path: [], message: error.message }]);
+            return c.json(refusal.toResponseBody(), 400);
+        }
+        if (error instanceof HTTPException) {
+            return c.json({ error: { code: 'BAD_REQUEST', message: error.message } }, error.status);
+        }
+        const requestId = requestIdFor(c);
+        await reportUnhandledError(onUnhandledError, error, c, requestId);
+        c.header(REQUEST_ID_HEADER, requestId);
+        return c.json({
+            error: {
+                code: 'INTERNAL_ERROR',
+                message: 'An unexpected error occurred while handling the request.',
+            },
+        }, 500);
+    };
+}
+export function handleNotFound(c) {
+    return c.json({
+        error: {
+            code: 'NOT_FOUND',
+            message: `No route matches ${c.req.method} ${new URL(c.req.url).pathname}.`,
+        },
+    }, 404);
+}
+//# sourceMappingURL=error-handler.js.map

package/dist/middleware/error-handler.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"error-handler.js","sourceRoot":"","sources":["../../src/middleware/error-handler.ts"],"names":[],"mappings":"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"}

package/dist/routes/notifications.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Notification endpoints. Each handler maps HTTP input to a VintaSend service
+ * call and the result back to the wire contract — no business logic beyond the
+ * translation itself.
+ */
+import { Hono } from 'hono';
+import type { TemplateSourceClient } from '../services/notification-preview.js';
+import type { NotificationServicePort } from '../services/notification-service-port.js';
+export type NotificationRoutesDependencies = {
+    getService: () => Promise<NotificationServicePort>;
+    getTemplateClient: () => TemplateSourceClient;
+    backendIdentifier?: string | undefined;
+};
+export declare function createNotificationRoutes(deps: NotificationRoutesDependencies): Hono;

package/dist/routes/notifications.js

@@ -0,0 +1,119 @@
+/**
+ * Notification endpoints. Each handler maps HTTP input to a VintaSend service
+ * call and the result back to the wire contract — no business logic beyond the
+ * translation itself.
+ */
+import { Hono } from 'hono';
+import { toWireCapabilities } from '../domain/capabilities.js';
+import { buildBackendFilter, buildOrderBy } from '../domain/filters.js';
+import { notificationListQuerySchema, paginationQuerySchema, resendBodySchema, } from '../domain/schemas.js';
+import { serializeNotification, serializeNotificationDetail, serializeUserNotification, } from '../domain/serialize.js';
+import { ApiError } from '../errors.js';
+import { buildNotificationPreview } from '../services/notification-preview.js';
+import { createPagedNotificationReader } from '../services/paged-notification-reader.js';
+import { validate } from './validation.js';
+/**
+ * One page of a listing, and whether the next page has a row.
+ *
+ * Backends are not required to count, so that is asked directly: a full page is followed by a
+ * one-row read of the first row after it, which is page `page * pageSize + 1` of one-row pages. A
+ * short page is the last one without asking. `read` takes the contract's 1-indexed pages.
+ */
+async function paginate(read, page, pageSize) {
+    const notifications = await read(page, pageSize);
+    const hasMore = notifications.length === pageSize && (await read(page * pageSize + 1, 1)).length > 0;
+    return {
+        data: notifications.map(serializeNotification),
+        page,
+        pageSize,
+        hasMore,
+    };
+}
+/**
+ * Looks a notification up as a user notification first, then as a one-off one.
+ */
+async function findNotification(service, id, backendIdentifier) {
+    const notification = (await service.getNotification(id, false, backendIdentifier)) ??
+        (await service.getOneOffNotification(id, false, backendIdentifier));
+    if (!notification) {
+        throw ApiError.notFound(`Notification with ID ${id} was not found.`);
+    }
+    return notification;
+}
+export function createNotificationRoutes(deps) {
+    const routes = new Hono();
+    const { backendIdentifier } = deps;
+    /**
+     * Reads pages the way the contract does: 1-indexed, translated for the backend.
+     */
+    const readerFor = async () => createPagedNotificationReader(await deps.getService(), backendIdentifier);
+    routes.get('/capabilities', async (c) => {
+        const reader = await readerFor();
+        return c.json({
+            data: toWireCapabilities(await reader.capabilities()),
+        });
+    });
+    routes.get('/notifications', validate('query', notificationListQuerySchema), async (c) => {
+        const query = c.req.valid('query');
+        const reader = await readerFor();
+        const capabilities = await reader.capabilities();
+        const filter = buildBackendFilter(query, capabilities);
+        const orderBy = buildOrderBy(query, capabilities);
+        return c.json(await paginate((page, pageSize) => reader.filterNotifications(filter, page, pageSize, orderBy), query.page, query.pageSize));
+    });
+    routes.get('/notifications/pending', validate('query', paginationQuerySchema), async (c) => {
+        const { page, pageSize } = c.req.valid('query');
+        const reader = await readerFor();
+        return c.json(await paginate(reader.getPendingNotifications, page, pageSize));
+    });
+    routes.get('/notifications/future', validate('query', paginationQuerySchema), async (c) => {
+        const { page, pageSize } = c.req.valid('query');
+        const reader = await readerFor();
+        return c.json(await paginate(reader.getFutureNotifications, page, pageSize));
+    });
+    routes.get('/notifications/one-off', validate('query', paginationQuerySchema), async (c) => {
+        const { page, pageSize } = c.req.valid('query');
+        const reader = await readerFor();
+        return c.json(await paginate(reader.getOneOffNotifications, page, pageSize));
+    });
+    routes.get('/notifications/:id', async (c) => {
+        const service = await deps.getService();
+        const notification = await findNotification(service, c.req.param('id'), backendIdentifier);
+        return c.json({
+            data: serializeNotificationDetail(notification),
+        });
+    });
+    routes.get('/notifications/:id/preview', async (c) => {
+        const service = await deps.getService();
+        const notification = await findNotification(service, c.req.param('id'), backendIdentifier);
+        const preview = await buildNotificationPreview({
+            service,
+            templateClient: deps.getTemplateClient(),
+            notification,
+        });
+        return c.json({ data: preview });
+    });
+    routes.post('/notifications/:id/resend', validate('json', resendBodySchema), async (c) => {
+        const { useStoredContext } = c.req.valid('json');
+        const service = await deps.getService();
+        const resent = await service.resendNotification(c.req.param('id'), useStoredContext);
+        if (!resent) {
+            throw ApiError.conflict('The notification could not be resent. It may not exist, may be a one-off notification, or may be scheduled for the future.');
+        }
+        return c.json({ data: serializeUserNotification(resent) }, 201);
+    });
+    routes.post('/notifications/:id/cancel', async (c) => {
+        const id = c.req.param('id');
+        const service = await deps.getService();
+        const notification = await findNotification(service, id, backendIdentifier);
+        if (notification.status !== 'PENDING_SEND') {
+            throw ApiError.conflict('Only notifications in PENDING_SEND status can be cancelled.');
+        }
+        await service.cancelNotification(id);
+        return c.json({
+            data: { id, status: 'CANCELLED' },
+        });
+    });
+    return routes;
+}
+//# sourceMappingURL=notifications.js.map

package/dist/routes/notifications.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"notifications.js","sourceRoot":"","sources":["../../src/routes/notifications.ts"],"names":[],"mappings":"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"}

package/dist/routes/validation.d.ts

@@ -0,0 +1,14 @@
+import type { ZodType } from 'zod';
+/**
+ * `zValidator` with the contract's error envelope: invalid input always comes back as a 400
+ * `BAD_REQUEST` listing the offending fields in `details.issues`.
+ *
+ * A `json` target also applies the contract's media-type rule. A request declaring a JSON media
+ * type must carry valid JSON (Hono refuses an empty or malformed one, and the error handler gives
+ * that refusal the same envelope). Any other request is read as `{}` when its body is empty, and
+ * refused when it is not.
+ */
+export declare function validate<Target extends 'query' | 'json' | 'param', Schema extends ZodType>(target: Target, schema: Schema): import("hono").MiddlewareHandler<import("hono").Env, string, {
+    in: (undefined extends import("zod").input<Schema> ? true : false) extends true ? { [K in Target]?: (import("zod").input<Schema> extends infer T ? T extends import("zod").input<Schema> ? T extends import("hono").ValidationTargets[K] ? T : { [K2 in keyof T]?: import("hono").ValidationTargets[K][K2] | undefined; } : never : never) | undefined; } : { [K_1 in Target]: import("zod").input<Schema> extends infer T ? T extends import("zod").input<Schema> ? T extends import("hono").ValidationTargets[K_1] ? T : { [K2_1 in keyof T]: import("hono").ValidationTargets[K_1][K2_1]; } : never : never; };
+    out: { [K_2 in Target]: import("zod").output<Schema>; };
+}>;

package/dist/routes/validation.js

@@ -0,0 +1,44 @@
+import { zValidator } from '@hono/zod-validator';
+import { invalidRequest } from '../errors.js';
+/** The media types Hono's validator parses as JSON: the same pattern as Hono's own `jsonRegex`. */
+const JSON_CONTENT_TYPE = /^application\/([a-z-.]+\+)?json(;\s*[a-zA-Z0-9-]+=([^;]+))*$/i;
+/**
+ * Whether the request carries a body Hono's validator would not read as JSON.
+ *
+ * Hono validates a request that declares no JSON media type as `{}`. That is right for an empty
+ * body — it is how an all-optional body is omitted — and wrong for any other: `curl -d
+ * '{"useStoredContext":true}'` is form-encoded unless told otherwise, and read as `{}` it would
+ * resend the notification with a context regenerated from current data instead of the one it was
+ * sent with. The templates management API applies the same rule.
+ *
+ * Decided by reading the body rather than from `content-length` or `transfer-encoding`: a body
+ * with no `Content-Type` (a `Uint8Array` handed to `fetch`) or a streamed HTTP/2 body carries
+ * neither header.
+ */
+async function hasNonJsonBody(c) {
+    const contentType = c.req.header('content-type');
+    if (contentType !== undefined && JSON_CONTENT_TYPE.test(contentType)) {
+        return false;
+    }
+    return (await c.req.text()).length > 0;
+}
+/**
+ * `zValidator` with the contract's error envelope: invalid input always comes back as a 400
+ * `BAD_REQUEST` listing the offending fields in `details.issues`.
+ *
+ * A `json` target also applies the contract's media-type rule. A request declaring a JSON media
+ * type must carry valid JSON (Hono refuses an empty or malformed one, and the error handler gives
+ * that refusal the same envelope). Any other request is read as `{}` when its body is empty, and
+ * refused when it is not.
+ */
+export function validate(target, schema) {
+    return zValidator(target, schema, async (result, c) => {
+        if (target === 'json' && (await hasNonJsonBody(c))) {
+            throw invalidRequest([{ path: [], message: 'Send the request body as application/json.' }]);
+        }
+        if (!result.success) {
+            throw invalidRequest(result.error.issues);
+        }
+    });
+}
+//# sourceMappingURL=validation.js.map

package/dist/routes/validation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"validation.js","sourceRoot":"","sources":["../../src/routes/validation.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,UAAU,EAAE,MAAM,qBAAqB,CAAC;AAIjD,OAAO,EAAE,cAAc,EAAE,MAAM,cAAc,CAAC;AAE9C,mGAAmG;AACnG,MAAM,iBAAiB,GAAG,+DAA+D,CAAC;AAE1F;;;;;;;;;;;;GAYG;AACH,KAAK,UAAU,cAAc,CAAC,CAAU;IACtC,MAAM,WAAW,GAAG,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,cAAc,CAAC,CAAC;IACjD,IAAI,WAAW,KAAK,SAAS,IAAI,iBAAiB,CAAC,IAAI,CAAC,WAAW,CAAC,EAAE,CAAC;QACrE,OAAO,KAAK,CAAC;IACf,CAAC;IACD,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,IAAI,EAAE,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC;AACzC,CAAC;AAED;;;;;;;;GAQG;AACH,MAAM,UAAU,QAAQ,CACtB,MAAc,EACd,MAAc;IAEd,OAAO,UAAU,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,CAAC,EAAE,EAAE;QACpD,IAAI,MAAM,KAAK,MAAM,IAAI,CAAC,MAAM,cAAc,CAAC,CAAC,CAAC,CAAC,EAAE,CAAC;YACnD,MAAM,cAAc,CAAC,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,OAAO,EAAE,4CAA4C,EAAE,CAAC,CAAC,CAAC;QAC9F,CAAC;QACD,IAAI,CAAC,MAAM,CAAC,OAAO,EAAE,CAAC;YACpB,MAAM,cAAc,CAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,CAAC;QAC5C,CAAC;IACH,CAAC,CAAC,CAAC;AACL,CAAC"}

package/dist/services/github-template-client.d.ts

@@ -0,0 +1,26 @@
+import { type GitHubTemplatePreviewConfig } from './github-template-preview-config.js';
+type GitHubTemplateClientOptions = {
+    cacheMaxEntries?: number;
+};
+type Fetcher = typeof fetch;
+export type TemplateContentRequest = {
+    templatePath: string;
+    gitCommitSha: string;
+};
+export declare class GitHubTemplateClient {
+    private readonly config;
+    private readonly fetcher;
+    private readonly cacheMaxEntries;
+    private readonly cache;
+    constructor(config: GitHubTemplatePreviewConfig, fetcher?: Fetcher, options?: GitHubTemplateClientOptions);
+    getTemplateContentByCommit(request: TemplateContentRequest): Promise<string>;
+    getLatestMainCommitSha(): Promise<string>;
+    private buildApiUrl;
+    private buildCacheKey;
+    private buildHeaders;
+    private setCache;
+    private buildHttpError;
+    private buildCommitLookupHttpError;
+}
+export declare function createGitHubTemplateClientFromEnv(options?: GitHubTemplateClientOptions): GitHubTemplateClient;
+export {};