vintasend-api 0.0.0-stage → 1.0.0-alpha6

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2017 Vinta Serviços e Soluções Tecnológicas Ltda
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,274 @@
-# Temporary Holding Version
+# VintaSend API
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+REST API that exposes a [VintaSend](https://github.com/vintasoftware/vintasend-ts)
+notification service over HTTP.
+
+It exists so the [VintaSend dashboard](https://github.com/vintasoftware/vintasend-ts-dashboard)
+no longer has to embed a notification service: the dashboard is now a pure API
+client, and any implementation of this contract can serve it — including a
+future one built on the Python `vintasend` package.
+
+**[`openapi.yaml`](./openapi.yaml) is the contract.** This repository is the
+TypeScript reference implementation of it, published to npm so a project can
+mount it rather than copy it.
+
+## Two ways to run it
+
+**Mounted in your own server** — the usual case for an app that already has
+one. `createApp` returns a [Hono](https://hono.dev) app, which takes a standard
+`Request` and returns a `Response`, so it mounts in a Next.js route handler, in
+TanStack Start, behind Express, or anywhere else that speaks `fetch`. You hand it
+the service you already built to send notifications, and your own check of who
+is calling. See [Mounting it](#mounting-it).
+
+**On its own** — the `vintasend-api` command runs a server configured from
+environment variables, behind one shared API key. See
+[Running it on its own](#running-it-on-its-own).
+
+Either way, the API ships no notification backend: database, adapters and
+template renderer are yours.
+
+## Installing
+
+```bash
+npm install vintasend-api vintasend
+```
+
+`vintasend` is a peer dependency, so your service and the API share one copy.
+Install the same release line for both: the API is released together with
+`vintasend`, and its version matches.
+
+## Architecture
+
+```
+┌─────────────────────┐   HTTPS + API key    ┌──────────────────┐
+│  Dashboard (Next)   │ ───────────────────▶ │  vintasend-api   │
+│  server-side only   │ ◀─────────────────── │  (this repo)     │
+└─────────────────────┘     JSON contract    └────────┬─────────┘
+                                                      │
+                                       ┌──────────────┴──────────────┐
+                                       │  Your VintaSend service     │
+                                       │  backend + adapters +       │
+                                       │  template renderer          │
+                                       └─────────────────────────────┘
+```
+
+The API owns everything that needs backend credentials — database access,
+template rendering, GitHub template lookups. The UI owns presentation and user
+authentication.
+
+## Endpoints
+
+| Method | Path | Purpose |
+| --- | --- | --- |
+| GET | `/health` | Liveness probe (unauthenticated) |
+| GET | `/api/v1/capabilities` | Filter/order capabilities of the configured backend |
+| GET | `/api/v1/notifications` | List notifications with filters, ordering and pagination |
+| GET | `/api/v1/notifications/pending` | Notifications awaiting send |
+| GET | `/api/v1/notifications/future` | Notifications scheduled for the future |
+| GET | `/api/v1/notifications/one-off` | One-off notifications |
+| GET | `/api/v1/notifications/{id}` | One notification, including context payloads |
+| GET | `/api/v1/notifications/{id}/preview` | Templates rendered at the notification's commit |
+| POST | `/api/v1/notifications/{id}/resend` | Resend a notification |
+| POST | `/api/v1/notifications/{id}/cancel` | Cancel a pending notification |
+
+Conventions worth knowing when implementing this contract elsewhere:
+
+- `page` is **1-indexed** in the API, in every implementation, and clients never
+  convert. What the backend wants is a separate question: the TypeScript
+  VintaSend backends are 0-indexed, the Python ones are 1-indexed. The offset
+  comes from the backend's `pagination.oneIndexed` capability — porting this
+  server's `page - 1` literally into a 1-indexed language is an off-by-one. The
+  capability is backend-facing and is not published by `/api/v1/capabilities`.
+- `hasMore` is `true` when the next page has at least one row, so a list that
+  exactly fills its last page never offers an empty one. Backends are not
+  required to produce a total count: after a full page, the server reads the one
+  row that would follow it.
+- List rows carry a `kind` field (`user` or `one-off`) so clients can
+  discriminate without sniffing for the presence of fields.
+- Timestamps are ISO-8601 UTC strings, `null` when unset — never `undefined`.
+- Errors always use the envelope `{ "error": { "code", "message", "details"? } }`.
+  Failures that come from the template source are `UPSTREAM_ERROR` (502), not a
+  generic 500.
+- Every 400 carries `details.issues: [{ path, message }]`, whatever the mistake
+  was. `path` names the field, and is empty for the body as a whole.
+- `FORBIDDEN` (403) is for a caller who is authenticated and not allowed — what a
+  host's own authentication answers. The API key alone never produces it.
+- Request bodies are JSON. A request declaring `application/json` (or any
+  `application/*+json`) must carry valid JSON. A request declaring no media type,
+  or another one, counts as an omitted body when it is empty and is a 400
+  otherwise — `curl -d` sends form encoding unless told otherwise, and reading
+  its body as `{}` would resend with a regenerated context instead of the stored
+  one.
+
+## Mounting it
+
+```ts
+// app/api/v1/[...path]/route.ts — a Next.js app router route handler
+import {
+  ApiError,
+  asNotificationServicePort,
+  createApp,
+  createGitHubTemplateClientFromEnv,
+} from 'vintasend-api';
+import { notificationService } from '@/lib/notifications';
+import { getSession } from '@/lib/auth';
+
+const app = createApp({
+  // The service your app already sends with. VintaSend services are generic over your
+  // notification config, so the port takes it through a cast confined to this one call.
+  getService: async () => asNotificationServicePort(notificationService),
+  // Runs before every /api/v1 route. Throw to refuse.
+  authenticate: async (c) => {
+    const user = await getSession(c.req.raw);
+    if (!user) throw ApiError.unauthorized('Sign in first.');
+    if (!user.canManageNotifications) throw ApiError.forbidden('Not allowed.');
+    return {};
+  },
+  // Where previews read templates from, at the commit a notification was sent with.
+  getTemplateClient: () => createGitHubTemplateClientFromEnv(),
+  // Every error not mapped to a contract error. Defaults to one redacted log line.
+  onUnhandledError: (error, _c, { requestId }) => errorTracker.capture(error, { requestId }),
+});
+
+const handler = (request: Request) => app.fetch(request);
+export { handler as GET, handler as POST };
+```
+
+Behind Express, hand `getRequestListener(app.fetch)` from `@hono/node-server` to a
+route that keeps the path whole — `server.all(...)`, not `server.use('/api/v1', ...)`,
+which strips the prefix the API's routes include.
+
+`authenticate` has the same shape in
+[`vintasend-templates-management-api`](https://github.com/vintasoftware/vintasend-ts-templates-management-api),
+so an app mounting both passes them one function. It may throw the `ApiError` of
+either package: both recognise an error by its name and code, not by its class.
+Throw `ApiError.unauthorized` for a caller with no valid credential and
+`ApiError.forbidden` for one you know and refuse: a 401 would tell a signed-in
+user to sign in again. For one shared secret, pass
+`authenticate: apiKeyAuthenticator(key)`, which compares in constant time.
+
+The app uses Web APIs only — no Node built-ins — so it runs wherever `fetch`
+does. The standalone server and the module-path service loader are the Node-only
+parts, and `createApp` loads neither.
+
+An unexpected error is reported to the client as a generic 500 with an
+`X-Request-Id` header. By default it is logged as one line — the error's name,
+the request id and the route pattern — and never with its message, its stack or
+the request: errors from a notification backend or provider can quote
+notification content and context values, which in the applications this API
+serves can be health data. `onUnhandledError` hands the error to your own
+tracker instead; keeping health data out of it is then your call. If it throws,
+the default line is logged in its place.
+
+## Running it on its own
+
+Every `/api/v1` request must carry the shared secret:
+
+```
+Authorization: Bearer $VINTASEND_API_KEY
+```
+
+The dashboard calls this API only from its own server side, so the key never
+reaches a browser. If you do need to call the API from a browser, set
+`VINTASEND_API_CORS_ORIGINS` to the allowed origins — and put a per-user auth
+layer in front of it first.
+
+```bash
+VINTASEND_API_KEY=… VINTASEND_SERVICE_MODULE=./vintasend.config.js npx vintasend-api
+```
+
+To work on this repository instead:
+
+```bash
+npm install
+cp .env.example .env
+npm run dev
+```
+
+## Configuring your VintaSend service
+
+The standalone server ships no backend of its own: which database, adapters and
+template renderer to use is a deployment decision. Point
+`VINTASEND_SERVICE_MODULE` at a module that default-exports a factory returning a
+configured VintaSend service:
+
+```ts
+// src/vintasend.config.ts
+import { VintaSendFactory } from 'vintasend';
+
+export default async function createVintaSendService() {
+  const backend = /* your backend */;
+  const renderer = /* your template renderer */;
+  const adapter = /* your notification adapter */;
+
+  return new VintaSendFactory<Config>().create(backend, [adapter], contextGenerators);
+}
+```
+
+Start from [`src/vintasend.config.example.ts`](./src/vintasend.config.example.ts),
+copying it to `src/vintasend.config.ts` (gitignored) so it is compiled along with
+the rest of `src`. The factory is called once at startup, and a failure there
+stops the server rather than surfacing on the first request.
+
+`VINTASEND_SERVICE_MODULE` accepts a path relative to the working directory or a
+bare package specifier. Use `./dist/vintasend.config.js` with `npm start`, and
+`./src/vintasend.config.ts` with `npm run dev`, which runs TypeScript directly.
+
+## Environment variables
+
+| Variable | Required | Description |
+| --- | --- | --- |
+| `VINTASEND_API_KEY` | yes | Shared secret clients must send as a bearer token. |
+| `VINTASEND_SERVICE_MODULE` | no | Module building your VintaSend service. Defaults to `./dist/vintasend.config.js`. |
+| `VINTASEND_BACKEND_IDENTIFIER` | no | Read from a non-primary backend registered in your service. |
+| `VINTASEND_API_CORS_ORIGINS` | no | Comma-separated browser origins allowed to call the API. |
+| `PORT` / `HOST` | no | Listen address. Defaults to `3333` / `0.0.0.0`. |
+| `GITHUB_REPO` | preview only | Repository holding the templates, as `owner/repo` or a full URL. |
+| `GITHUB_API_KEY` | preview only | Token with read access to that repository. |
+| `GITHUB_API_BASE_URL` | no | Defaults to `https://api.github.com`. |
+| `GITHUB_TEMPLATES_BASE_PATH` | no | Prefix added to template paths before the GitHub lookup. |
+
+The `GITHUB_*` variables are only read when `/preview` is called, so the API
+runs fine without them if you do not use template previews.
+
+## Development
+
+```bash
+npm run dev        # watch mode
+npm test           # vitest
+npm run typecheck  # tsc --noEmit
+npm run lint       # biome
+npm run build      # compile to dist/
+npm start          # run the compiled server
+```
+
+Tests drive the real Hono app through `app.request()` with an injected fake
+service, so they cover routing, auth, validation, filter negotiation and
+serialization without needing a database.
+
+## Implementing this contract in another language
+
+1. Read `openapi.yaml` — it is normative, including status codes and error codes.
+2. Mirror the `hasMore` rule (another page has a row) and the `kind`
+   discriminator exactly; the dashboard depends on both.
+3. Take the page offset from your backend's `pagination.oneIndexed` capability,
+   not from this implementation. The wire stays 1-indexed either way, so a
+   1-indexed backend passes the page straight through — no `- 1`. Apply it to
+   every paginated read, and keep the capability out of the `/capabilities`
+   response so no client converts on top of you.
+4. Treat `stringLookups.caseSensitive` and `stringLookups.caseInsensitive` as
+   independent: a backend can be incapable of either one, and deriving one from
+   the other declines the single lookup such a backend actually supports.
+5. Negotiate string lookups and ordering against your backend's capabilities,
+   and report what you support from `/api/v1/capabilities`. Dropping an
+   unsupported ordering is correct; failing the request is not.
+6. Report template-source failures as `UPSTREAM_ERROR` (502) rather than a
+   generic 500: a rate-limited or unreachable template host is not a fault of
+   the API, and the dashboard shows the message to the operator.
+7. Keep the error envelope identical — the dashboard branches on `error.code` —
+   including `details.issues` on every 400 and the request-body rule.
+
+## License
+
+MIT

package/dist/app.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Builds the HTTP application.
+ *
+ * Everything the API needs from the outside world — who the caller is, the VintaSend service and
+ * the template source — is injected, so the app can be exercised in tests without a database, a
+ * mail provider, or GitHub, and mounted inside a host's own server behind its own authentication.
+ */
+import { Hono } from 'hono';
+import { type Authenticator } from './middleware/authenticate.js';
+import { type UnhandledErrorHandler } from './middleware/error-handler.js';
+import type { TemplateSourceClient } from './services/notification-preview.js';
+import type { NotificationServicePort } from './services/notification-service-port.js';
+export type AppDependencies = {
+    /**
+     * Runs before every `/api/v1` route. It refuses a caller by throwing `ApiError.unauthorized` or
+     * `ApiError.forbidden`. `apiKeyAuthenticator(key)` is the shared-secret case.
+     */
+    authenticate: Authenticator;
+    getService: () => Promise<NotificationServicePort>;
+    /** Where previews read a notification's templates from, at the commit it was sent with. */
+    getTemplateClient: () => TemplateSourceClient;
+    backendIdentifier?: string | undefined;
+    corsOrigins?: string[];
+    /**
+     * Receives every error the API does not map to a contract error. Defaults to a single log line
+     * with the error's name, a request id and the route — never the error object or the request.
+     * If the handler throws, that default line is logged instead. The client gets the generic 500
+     * either way.
+     */
+    onUnhandledError?: UnhandledErrorHandler;
+};
+export declare const API_BASE_PATH = "/api/v1";
+export declare function createApp(deps: AppDependencies): Hono;

package/dist/app.js

@@ -0,0 +1,33 @@
+/**
+ * Builds the HTTP application.
+ *
+ * Everything the API needs from the outside world — who the caller is, the VintaSend service and
+ * the template source — is injected, so the app can be exercised in tests without a database, a
+ * mail provider, or GitHub, and mounted inside a host's own server behind its own authentication.
+ */
+import { Hono } from 'hono';
+import { cors } from 'hono/cors';
+import { API_VERSION } from './contract/types.js';
+import { authenticateWith } from './middleware/authenticate.js';
+import { createErrorHandler, handleNotFound, } from './middleware/error-handler.js';
+import { createNotificationRoutes } from './routes/notifications.js';
+export const API_BASE_PATH = `/api/${API_VERSION}`;
+export function createApp(deps) {
+    const app = new Hono();
+    app.onError(createErrorHandler(deps.onUnhandledError));
+    app.notFound(handleNotFound);
+    if (deps.corsOrigins && deps.corsOrigins.length > 0) {
+        const allowedOrigins = deps.corsOrigins;
+        app.use(`${API_BASE_PATH}/*`, cors({
+            origin: (origin) => (allowedOrigins.includes(origin) ? origin : null),
+            allowHeaders: ['Authorization', 'Content-Type'],
+            allowMethods: ['GET', 'POST', 'OPTIONS'],
+        }));
+    }
+    // Unauthenticated: used by load balancers and container health checks.
+    app.get('/health', (c) => c.json({ status: 'ok', apiVersion: API_VERSION }));
+    app.use(`${API_BASE_PATH}/*`, authenticateWith(deps.authenticate));
+    app.route(API_BASE_PATH, createNotificationRoutes(deps));
+    return app;
+}
+//# sourceMappingURL=app.js.map

package/dist/app.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"app.js","sourceRoot":"","sources":["../src/app.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,IAAI,EAAE,MAAM,MAAM,CAAC;AAC5B,OAAO,EAAE,IAAI,EAAE,MAAM,WAAW,CAAC;AAEjC,OAAO,EAAE,WAAW,EAAuB,MAAM,qBAAqB,CAAC;AACvE,OAAO,EAAsB,gBAAgB,EAAE,MAAM,8BAA8B,CAAC;AACpF,OAAO,EACL,kBAAkB,EAClB,cAAc,GAEf,MAAM,+BAA+B,CAAC;AACvC,OAAO,EAAE,wBAAwB,EAAE,MAAM,2BAA2B,CAAC;AAwBrE,MAAM,CAAC,MAAM,aAAa,GAAG,QAAQ,WAAW,EAAE,CAAC;AAEnD,MAAM,UAAU,SAAS,CAAC,IAAqB;IAC7C,MAAM,GAAG,GAAG,IAAI,IAAI,EAAE,CAAC;IAEvB,GAAG,CAAC,OAAO,CAAC,kBAAkB,CAAC,IAAI,CAAC,gBAAgB,CAAC,CAAC,CAAC;IACvD,GAAG,CAAC,QAAQ,CAAC,cAAc,CAAC,CAAC;IAE7B,IAAI,IAAI,CAAC,WAAW,IAAI,IAAI,CAAC,WAAW,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACpD,MAAM,cAAc,GAAG,IAAI,CAAC,WAAW,CAAC;QACxC,GAAG,CAAC,GAAG,CACL,GAAG,aAAa,IAAI,EACpB,IAAI,CAAC;YACH,MAAM,EAAE,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,cAAc,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,MAAM,CAAC,CAAC,CAAC,IAAI,CAAC;YACrE,YAAY,EAAE,CAAC,eAAe,EAAE,cAAc,CAAC;YAC/C,YAAY,EAAE,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,CAAC;SACzC,CAAC,CACH,CAAC;IACJ,CAAC;IAED,uEAAuE;IACvE,GAAG,CAAC,GAAG,CAAC,SAAS,EAAE,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAC,IAAI,CAAiB,EAAE,MAAM,EAAE,IAAI,EAAE,UAAU,EAAE,WAAW,EAAE,CAAC,CAAC,CAAC;IAE7F,GAAG,CAAC,GAAG,CAAC,GAAG,aAAa,IAAI,EAAE,gBAAgB,CAAC,IAAI,CAAC,YAAY,CAAC,CAAC,CAAC;IACnE,GAAG,CAAC,KAAK,CAAC,aAAa,EAAE,wBAAwB,CAAC,IAAI,CAAC,CAAC,CAAC;IAEzD,OAAO,GAAG,CAAC;AACb,CAAC"}

package/dist/config.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Server configuration read from the environment. Validated once at startup so
+ * a misconfigured deployment fails immediately instead of on the first request.
+ */
+export type ServerConfig = {
+    port: number;
+    host: string;
+    apiKey: string;
+    corsOrigins: string[];
+    serviceModule: string;
+    backendIdentifier: string | undefined;
+};
+export declare function loadServerConfig(env?: NodeJS.ProcessEnv): ServerConfig;

package/dist/config.js

@@ -0,0 +1,39 @@
+/**
+ * Server configuration read from the environment. Validated once at startup so
+ * a misconfigured deployment fails immediately instead of on the first request.
+ */
+const DEFAULT_PORT = 3333;
+const DEFAULT_HOST = '0.0.0.0';
+const DEFAULT_SERVICE_MODULE = './dist/vintasend.config.js';
+function splitList(value) {
+    if (!value) {
+        return [];
+    }
+    return value
+        .split(',')
+        .map((entry) => entry.trim())
+        .filter(Boolean);
+}
+export function loadServerConfig(env = process.env) {
+    const errors = [];
+    const apiKey = env.VINTASEND_API_KEY?.trim();
+    if (!apiKey) {
+        errors.push('VINTASEND_API_KEY is required');
+    }
+    const port = Number(env.PORT ?? DEFAULT_PORT);
+    if (!Number.isInteger(port) || port <= 0) {
+        errors.push('PORT must be a positive integer');
+    }
+    if (errors.length > 0) {
+        throw new Error(`Invalid API configuration:\n${errors.map((e) => `  - ${e}`).join('\n')}`);
+    }
+    return {
+        port,
+        host: env.HOST?.trim() || DEFAULT_HOST,
+        apiKey: apiKey,
+        corsOrigins: splitList(env.VINTASEND_API_CORS_ORIGINS),
+        serviceModule: env.VINTASEND_SERVICE_MODULE?.trim() || DEFAULT_SERVICE_MODULE,
+        backendIdentifier: env.VINTASEND_BACKEND_IDENTIFIER?.trim() || undefined,
+    };
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.js","sourceRoot":"","sources":["../src/config.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAWH,MAAM,YAAY,GAAG,IAAI,CAAC;AAC1B,MAAM,YAAY,GAAG,SAAS,CAAC;AAC/B,MAAM,sBAAsB,GAAG,4BAA4B,CAAC;AAE5D,SAAS,SAAS,CAAC,KAAyB;IAC1C,IAAI,CAAC,KAAK,EAAE,CAAC;QACX,OAAO,EAAE,CAAC;IACZ,CAAC;IACD,OAAO,KAAK;SACT,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC;SAC5B,MAAM,CAAC,OAAO,CAAC,CAAC;AACrB,CAAC;AAED,MAAM,UAAU,gBAAgB,CAAC,MAAyB,OAAO,CAAC,GAAG;IACnE,MAAM,MAAM,GAAa,EAAE,CAAC;IAE5B,MAAM,MAAM,GAAG,GAAG,CAAC,iBAAiB,EAAE,IAAI,EAAE,CAAC;IAC7C,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,CAAC,IAAI,CAAC,+BAA+B,CAAC,CAAC;IAC/C,CAAC;IAED,MAAM,IAAI,GAAG,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,YAAY,CAAC,CAAC;IAC9C,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,EAAE,CAAC;QACzC,MAAM,CAAC,IAAI,CAAC,iCAAiC,CAAC,CAAC;IACjD,CAAC;IAED,IAAI,MAAM,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;QACtB,MAAM,IAAI,KAAK,CAAC,+BAA+B,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC7F,CAAC;IAED,OAAO;QACL,IAAI;QACJ,IAAI,EAAE,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,YAAY;QACtC,MAAM,EAAE,MAAgB;QACxB,WAAW,EAAE,SAAS,CAAC,GAAG,CAAC,0BAA0B,CAAC;QACtD,aAAa,EAAE,GAAG,CAAC,wBAAwB,EAAE,IAAI,EAAE,IAAI,sBAAsB;QAC7E,iBAAiB,EAAE,GAAG,CAAC,4BAA4B,EAAE,IAAI,EAAE,IAAI,SAAS;KACzE,CAAC;AACJ,CAAC"}

package/dist/contract/types.d.ts

@@ -0,0 +1,196 @@
+/**
+ * Wire contract for the VintaSend dashboard API.
+ *
+ * These types describe the JSON payloads exchanged over HTTP. They intentionally
+ * avoid importing anything from `vintasend`: any implementation of this contract
+ * (the TypeScript one in this repo, a future Python one) must produce exactly
+ * these shapes, and any UI consuming the API only needs these definitions.
+ *
+ * All timestamps are ISO-8601 strings in UTC.
+ */
+export declare const API_VERSION = "v1";
+export type NotificationStatus = 'PENDING_SEND' | 'SENT' | 'FAILED' | 'READ' | 'CANCELLED';
+export type NotificationType = 'EMAIL' | 'SMS' | 'PUSH' | 'IN_APP';
+export type JsonValue = string | number | boolean | null | JsonValue[] | {
+    [key: string]: JsonValue;
+};
+/**
+ * Attachment metadata exposed on notification details.
+ */
+export type NotificationAttachment = {
+    id: string;
+    filename: string;
+    contentType: string;
+    size: number;
+    description?: string;
+};
+/**
+ * Fields shared by regular and one-off notifications in list responses.
+ */
+type NotificationBase = {
+    id: string;
+    notificationType: NotificationType;
+    title: string | null;
+    contextName: string;
+    status: NotificationStatus;
+    sendAfter: string | null;
+    sentAt: string | null;
+    readAt: string | null;
+    createdAt: string | null;
+    updatedAt: string | null;
+    adapterUsed: string | null;
+    bodyTemplate: string;
+    subjectTemplate: string | null;
+    gitCommitSha: string | null;
+    /**
+     * The template version this notification asked for, pinned when it was created or updated.
+     * `null` means it was left unpinned and renders whatever version is current at send time.
+     * Always `null` when the service's template renderer has no versions.
+     */
+    requestedTemplateVersion: number | null;
+    /**
+     * The template version the renderer reported after the notification was sent. `null` until it
+     * has been sent, and always `null` when the template renderer has no versions. On an unpinned
+     * notification this is the only record of what went out.
+     */
+    usedTemplateVersion: number | null;
+    tenant: string | null;
+};
+/**
+ * A notification addressed to a known user.
+ */
+export type UserNotification = NotificationBase & {
+    kind: 'user';
+    userId: string;
+};
+/**
+ * A notification addressed to a raw email/phone, without a user record.
+ */
+export type OneOffNotification = NotificationBase & {
+    kind: 'one-off';
+    emailOrPhone: string;
+    firstName: string | null;
+    lastName: string | null;
+};
+/**
+ * List-view notification. `kind` discriminates the two variants.
+ */
+export type Notification = UserNotification | OneOffNotification;
+type NotificationDetailFields = {
+    contextUsed: JsonValue | null;
+    contextParameters: JsonValue | null;
+    extraParams: JsonValue | null;
+    attachments: NotificationAttachment[];
+};
+export type UserNotificationDetail = UserNotification & NotificationDetailFields;
+export type OneOffNotificationDetail = OneOffNotification & NotificationDetailFields;
+/**
+ * Detail-view notification, including the (potentially large) context payloads.
+ */
+export type NotificationDetail = UserNotificationDetail | OneOffNotificationDetail;
+export type NotificationOrderByField = 'sendAfter' | 'sentAt' | 'readAt' | 'createdAt' | 'updatedAt';
+export type NotificationOrderDirection = 'asc' | 'desc';
+/**
+ * Query parameters accepted by `GET /api/v1/notifications`.
+ * Every field is optional; date fields are ISO-8601 strings.
+ */
+export type NotificationListQuery = {
+    page?: number;
+    pageSize?: number;
+    status?: NotificationStatus;
+    notificationType?: NotificationType;
+    adapterUsed?: string;
+    userId?: string;
+    bodyTemplate?: string;
+    subjectTemplate?: string;
+    contextName?: string;
+    tenant?: string;
+    /** Notifications pinned to this template version. Unpinned notifications never match. */
+    requestedTemplateVersion?: number;
+    /** Notifications that rendered this template version. Unsent notifications never match. */
+    usedTemplateVersion?: number;
+    createdAtFrom?: string;
+    createdAtTo?: string;
+    sentAtFrom?: string;
+    sentAtTo?: string;
+    orderByField?: NotificationOrderByField;
+    orderByDirection?: NotificationOrderDirection;
+};
+/**
+ * Envelope returned by every paginated endpoint. `page` is 1-indexed, whatever
+ * numbering the backend behind the API uses.
+ */
+export type PaginatedResponse<T> = {
+    data: T[];
+    page: number;
+    pageSize: number;
+    /**
+     * True when the next page has at least one row, so a list that exactly fills its last page
+     * never offers an empty one. There is no total: backends are not required to count.
+     */
+    hasMore: boolean;
+};
+/**
+ * Envelope returned by every single-resource endpoint.
+ */
+export type DataResponse<T> = {
+    data: T;
+};
+/**
+ * Filter capabilities advertised by the configured backend. Consumers use it to
+ * hide sorting/filtering affordances the backend cannot honour. Keys mirror
+ * VintaSend's capability keys (e.g. `orderBy.sentAt`, `stringLookups.includes`).
+ *
+ * They describe the backend, not the API: `pagination.oneIndexed` reports how
+ * the backend numbers pages, while the API's own `page` is always 1-indexed.
+ */
+export type FilterCapabilities = Record<string, boolean>;
+/**
+ * Payload of `GET /api/v1/notifications/{id}/preview` on success.
+ */
+export type NotificationPreview = {
+    gitCommitSha: string;
+    bodyTemplatePath: string;
+    subjectTemplatePath: string | null;
+    renderedBodyHtml: string;
+    renderedSubjectHtml: string;
+};
+/**
+ * Payload of `POST /api/v1/notifications/{id}/cancel` on success.
+ */
+export type CancelledNotification = {
+    id: string;
+    status: NotificationStatus;
+};
+/**
+ * Machine-readable error codes. Clients should branch on these, not on messages.
+ */
+export type ApiErrorCode = 'BAD_REQUEST' | 'UNAUTHORIZED' | 'FORBIDDEN' | 'NOT_FOUND' | 'CONFLICT' | 'PREVIEW_UNAVAILABLE' | 'UPSTREAM_ERROR' | 'INTERNAL_ERROR';
+/**
+ * One thing wrong with a request, in a 400's `details.issues`.
+ *
+ * `path` is the dotted field, and empty for the body as a whole or for a refusal that names no
+ * field.
+ */
+export type ApiErrorIssue = {
+    path: string;
+    message: string;
+};
+/**
+ * Error envelope returned with every non-2xx response.
+ *
+ * Every 400 carries `details.issues: ApiErrorIssue[]`, whatever the mistake was, and may carry
+ * other keys beside it.
+ */
+export type ApiErrorResponse = {
+    error: {
+        code: ApiErrorCode;
+        message: string;
+        details?: JsonValue;
+    };
+};
+export type HealthResponse = {
+    status: 'ok';
+    apiVersion: string;
+};
+export {};

package/dist/contract/types.js

@@ -0,0 +1,12 @@
+/**
+ * Wire contract for the VintaSend dashboard API.
+ *
+ * These types describe the JSON payloads exchanged over HTTP. They intentionally
+ * avoid importing anything from `vintasend`: any implementation of this contract
+ * (the TypeScript one in this repo, a future Python one) must produce exactly
+ * these shapes, and any UI consuming the API only needs these definitions.
+ *
+ * All timestamps are ISO-8601 strings in UTC.
+ */
+export const API_VERSION = 'v1';
+//# sourceMappingURL=types.js.map

package/dist/contract/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/contract/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,MAAM,CAAC,MAAM,WAAW,GAAG,IAAI,CAAC"}

package/dist/domain/capabilities.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The capability map is a backend report, and only part of it is any of a
+ * client's business.
+ *
+ * `/api/v1/capabilities` exists so consumers can hide sorting and filtering
+ * affordances the backend cannot honour. Pagination conventions are not that:
+ * the wire contract is unconditionally 1-indexed and this server does the
+ * conversion, so publishing `pagination.oneIndexed` would only invite a client
+ * to convert a second time.
+ */
+import type { NotificationFilterCapabilities } from 'vintasend';
+import type { FilterCapabilities } from '../contract/types.js';
+export declare function toWireCapabilities(capabilities: NotificationFilterCapabilities): FilterCapabilities;