@rakun-kit/core 1.4.10 → 1.5.0

package/dist/docs/index.md

@@ -0,0 +1,238 @@
+# Rakun AI manual and package index
+
+This is the entry point for coding agents working on an application that uses
+Rakun. It describes the package map, the normal architecture, and the public
+surface of `@rakun-kit/core`. Read the manual for every adapter used by the
+application before editing its integration.
+
+In an installed project this file is located at
+`node_modules/@rakun-kit/core/dist/docs/index.md`. Other package manuals use the
+same `dist/docs/index.md` location.
+
+## Package map
+
+| Package                         | Use it for                                                                          | Installed manual                                                |
+| ------------------------------- | ----------------------------------------------------------------------------------- | --------------------------------------------------------------- |
+| `@rakun-kit/core`               | Domain model, bootstrap, operations, auth, routes, media, mail and shared contracts | This file                                                       |
+| `@rakun-kit/next`               | Next.js App Router API, manager, media and web rendering                            | `node_modules/@rakun-kit/next/dist/docs/index.md`               |
+| `@rakun-kit/express`            | Express API and local-media adapter                                                 | `node_modules/@rakun-kit/express/dist/docs/index.md`            |
+| `@rakun-kit/trpc`               | Typed tRPC router for manager and web operations                                    | `node_modules/@rakun-kit/trpc/dist/docs/index.md`               |
+| `@rakun-kit/react`              | Framework-neutral React module rendering                                            | `node_modules/@rakun-kit/react/dist/docs/index.md`              |
+| `@rakun-kit/manager-react`      | Manager UI, clients, navigation and plugin runtime                                  | `node_modules/@rakun-kit/manager-react/dist/docs/index.md`      |
+| `@rakun-kit/manager-locales`    | Optional manager UI locale packs                                                    | `node_modules/@rakun-kit/manager-locales/dist/docs/index.md`    |
+| `@rakun-kit/s3`                 | S3 and S3-compatible media storage                                                  | `node_modules/@rakun-kit/s3/dist/docs/index.md`                 |
+| `@rakun-kit/smtp`               | SMTP mail delivery                                                                  | `node_modules/@rakun-kit/smtp/dist/docs/index.md`               |
+| `@rakun-kit/resend`             | Resend mail delivery                                                                | `node_modules/@rakun-kit/resend/dist/docs/index.md`             |
+| `@rakun-kit/jsx-email`          | Typed JSX Email template rendering                                                  | `node_modules/@rakun-kit/jsx-email/dist/docs/index.md`          |
+| `@rakun-kit/openai`             | OpenAI-backed automatic content translation                                         | `node_modules/@rakun-kit/openai/dist/docs/index.md`             |
+| `@rakun-kit/plugin-code-editor` | Code blocks in manager RichText fields                                              | `node_modules/@rakun-kit/plugin-code-editor/dist/docs/index.md` |
+| `create-rakun-app`              | Official project generator and framework starter templates                          | `node_modules/create-rakun-app/dist/docs/index.md`              |
+
+Choose one server adapter (`next` or `express`). Add `trpc` only if the host
+wants tRPC, one media adapter if uploads are required, and one mail adapter if
+outbound mail is required. `manager-react` is normally consumed through the
+Next adapter; use it directly for custom hosts.
+
+`preview` and `preview-next` are private example applications in the Rakun
+repository, not installable packages, so they do not have installed manuals.
+
+## Typical architecture
+
+1. Define literals, content types, routes and any custom operations in
+   framework-neutral server modules.
+2. Call `rakunBootstrap` once, or pass the same options to an adapter that calls
+   `ensureRakunBootstrap`.
+3. Mount the API with `@rakun-kit/next` or `@rakun-kit/express`.
+4. Render the manager and web modules with the corresponding React integration.
+5. Keep browser code away from server secrets and server-only package entries.
+
+## Install and peer requirements
+
+```sh
+bun add @rakun-kit/core mongodb bcrypt sharp zod
+```
+
+`mongodb`, `bcrypt` and `sharp` are peer dependencies. Install only compatible
+versions declared by the package. Adapters and optional services are separate
+packages.
+
+## Bootstrap
+
+```ts
+import { ContentType, f, rakunBootstrap } from '@rakun-kit/core'
+
+const Article = new ContentType({
+  name: 'Article',
+  menu: { title: 'Articles', icon: 'newspaper', category: 'Content' },
+  fields: {
+    title: f.string().required(),
+    slug: f.string().type('Slug').required(),
+    body: f.string().type('RichText'),
+  },
+  uniques: [['slug']],
+  listFields: ['title', 'slug'],
+})
+
+rakunBootstrap({
+  literals,
+  contentTypes: [Article],
+  routes,
+  mongo: {
+    MONGO_URI: process.env.MONGO_URI!,
+    ENVIRONMENT: process.env.NODE_ENV === 'test' ? 'test' : 'production',
+  },
+})
+```
+
+Important bootstrap options are `literals`, `contentTypes`,
+`internalContentTypes`, `routes`, `apiOperations`, `plugins`, `mongo`, `media`,
+`mail`, `translation`, `managerLanguages`, `login`, `accountRecovery`, `logger`
+and `syncRoutes`.
+
+- `rakunBootstrap(options)` registers configuration synchronously.
+- `ensureRakunBootstrap(options)` registers it only if needed. Framework
+  adapters use this to tolerate development reloads.
+- `ensureRakunInitialized()` initializes logger, MongoDB, media and route sync.
+  It is concurrency-safe and retries after a failed initialization.
+
+Do not import React, Next, Express, Vite or tRPC into core configuration modules.
+
+## Content types and fields
+
+`ContentType` describes a collection and derives its validation and TypeScript
+shapes. Use `f` factories rather than handwritten storage schemas.
+`Fields` remains available as a backward-compatible alias and references the
+same object, but new code and examples should prefer `f`.
+
+Common factories include string, number, boolean, date, object, relation, file,
+blocks and array/list forms. Chain field modifiers such as `.required()`,
+`.multiple()`, `.managerOnly()`, `.apiOnly()` and `.noDynamic()` when applicable.
+Special manager editors are selected with `.type(...)`, for example `Slug`,
+`RichText`, `Email`, `Password` and `Image`.
+
+`f.link()` accepts either a direct URL string or an internal
+`{ routeId, contentTypeId }` reference. Internal references resolve to localized
+paths in web output; direct URLs pass through unchanged.
+
+Use `iterator` for ordered page modules. Rakun stores it as the reserved
+`_iterator` field. `linkedIterator: true` shares a canonical module structure
+between documents while allowing a document to be explicitly unlinked.
+
+```ts
+const Page = new ContentType({
+  name: 'Page',
+  fields: {
+    title: f.string().required(),
+    slug: f.string().type('Slug').required(),
+  },
+  iterator: [{ contentType: Hero, type: 'new' }],
+  linkedIterator: true,
+})
+```
+
+Content type names, field names and reserved fields are persisted API. Do not
+rename them without a data migration and a review of manager and web consumers.
+Use `.withHooks(...)` for lifecycle behavior; keep mutations and secrets out of
+`onGet` transformations unless that behavior is explicitly intended.
+
+## Routes and web output
+
+Routes connect a content type field to a public URL. A page route may also have
+a fixed `layout` with module slots and a `{ type: 'content' }` insertion point.
+When a content type has a `hasPage: true` route, core adds optional `_seo`
+metadata and can expose generated `href` values to dynamic data.
+
+Use `@rakun-kit/core/web` for framework-neutral web types/utilities. Use the
+Next or React manual for actual rendering. Route changes can affect configured
+redirects, sitemap, robots output, preview, and adapter behavior.
+
+## Custom operations
+
+Define public API behavior with the operation helpers and Zod input/output
+schemas. Register the map through `apiOperations` so adapters and typed clients
+share one contract.
+
+```ts
+import { defineOperation } from '@rakun-kit/core'
+import { z } from 'zod'
+
+export const apiOperations = {
+  'demo.hello': defineOperation({
+    access: 'public',
+    kind: 'query',
+    method: 'get',
+    input: z.object({ name: z.string() }),
+    output: z.object({ message: z.string() }),
+    resolve: ({ input }) => ({ message: `Hello ${input.name}` }),
+  }),
+}
+```
+
+Keep operations in server modules. Client code should import the operation map
+with `import type` and use the typed client supplied by its adapter.
+
+Every API error, including expected 4xx errors, must reach Rakun's persistent
+event log without persisting payloads, credentials, sensitive causes or raw
+internal error messages. Successful mutations already emit
+`<operation>.succeeded`; add explicit domain events for meaningful phases,
+external effects or partial outcomes. Queries are not logged by default.
+
+## Request context, auth and permissions
+
+Adapters create a Rakun request context from headers, cookies and their response
+abstraction. Prefer existing helpers such as `getUser`, `checkPermissions` and
+`checkOwnership`; do not duplicate authorization rules in application code.
+
+External manager login adapters are configured under `login.adapters`.
+Provider emails must be verified and match an existing manager user; Rakun does
+not provision users automatically. Password login can use persistent IP
+blocking. Account recovery requires both a mail service and
+`accountRecovery.passwordReset` configuration.
+
+## Media, mail and translation
+
+Core defines service contracts; concrete integrations are separate:
+
+- Media: use `@rakun-kit/s3`, or local media from the selected framework
+  adapter. Configure the result as `media` in bootstrap.
+- Mail: use `@rakun-kit/smtp` or `@rakun-kit/resend`; optionally render typed
+  templates with `@rakun-kit/jsx-email`. Configure delivery as `mail`.
+- Translation: use `@rakun-kit/openai` or implement the core translation
+  adapter contract. Configure it as `translation`.
+
+Never expose adapter credentials in client modules. Public and private media
+have different URL semantics; do not replace stored media objects with raw URLs.
+
+## Manager languages and user-facing text
+
+Web/content-facing text belongs in Rakun literals. Manager UI text belongs in
+the manager catalog. English manager copy is built into `manager-react`; add
+optional packs such as Spanish through `@rakun-kit/manager-locales/es` and
+`managerLanguages`.
+
+Project-defined manager labels may use arbitrary keys. Field labels follow
+`field.<fieldName>` and layout slots follow `layoutModule.<layoutKey>`.
+
+## Public entrypoints
+
+- `@rakun-kit/core`: bootstrap and the main domain/runtime API.
+- `@rakun-kit/core/contracts`: shared schemas, operation and locale contracts.
+- `@rakun-kit/core/client`: browser-safe client types and utilities.
+- `@rakun-kit/core/manager`: manager operation metadata and types.
+- `@rakun-kit/core/web`: web output types and utilities.
+- `@rakun-kit/core/types`: content-type-derived helpers.
+- `@rakun-kit/core/logger`, `/errors`, `/literals`, `/api-utils`, `/plugins`,
+  `/event-log` and `/internal-content-types`: focused public surfaces.
+
+Import only declared package entrypoints. Do not reach into `dist/esm`,
+`dist/cjs` or source paths.
+
+## Agent checklist
+
+- Identify the host adapter and read its installed manual.
+- Confirm an API is exported before importing it.
+- Preserve the server/browser boundary and use `import type` for contracts.
+- Reuse core validation, auth, operation, logging and service abstractions.
+- Treat persisted names and public schemas as compatibility boundaries.
+- Update application tests when content, routes, permissions or operation
+  behavior changes.

package/dist/esm/api/context.d.ts

@@ -11,6 +11,7 @@ export type RakunRequestContext = {
     req?: {
         headers?: Record<string, string | string[] | undefined>;
         cookies?: Record<string, string>;
+        ip?: string;
     };
     res?: {
         setHeader: (name: string, value: string | string[]) => void;
@@ -22,6 +23,7 @@ export type RakunRequestContext = {
 export type RakunRequestContextInput = {
     headers?: Record<string, string | string[] | undefined>;
     cookies?: Record<string, string>;
+    ip?: string;
     res: {
         setHeader: (name: string, value: string | string[]) => void;
         cookie?: (name: string, value: string, options?: CookieOptions) => void;

package/dist/esm/api/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/api/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAK9D,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE;QACJ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;QACxD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;KAClC,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC;QAC5D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;KACzE,CAAC;IACF,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,MAAM,iBAAiB,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,GAAG,EAAE;QACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC;QAC5D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;KACzE,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,OAAO,wBAAwB,KAC9B,OAAO,CAAC,mBAAmB,CA+B7B,CAAC"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../../src/api/context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,2BAA2B,CAAC;AAK9D,MAAM,MAAM,aAAa,GAAG;IAC1B,QAAQ,CAAC,EAAE,OAAO,CAAC;IACnB,MAAM,CAAC,EAAE,OAAO,CAAC;IACjB,QAAQ,CAAC,EAAE,KAAK,GAAG,QAAQ,GAAG,MAAM,CAAC;IACrC,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,GAAG,CAAC,EAAE;QACJ,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;QACxD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QACjC,EAAE,CAAC,EAAE,MAAM,CAAC;KACb,CAAC;IACF,GAAG,CAAC,EAAE;QACJ,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC;QAC5D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;KACzE,CAAC;IACF,IAAI,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;IAChC,OAAO,EAAE,MAAM,iBAAiB,CAAC;CAClC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG;IACrC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IACxD,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,GAAG,EAAE;QACH,SAAS,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,IAAI,CAAC;QAC5D,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,aAAa,KAAK,IAAI,CAAC;KACzE,CAAC;CACH,CAAC;AAEF,eAAO,MAAM,oBAAoB,GAC/B,OAAO,wBAAwB,KAC9B,OAAO,CAAC,mBAAmB,CAgC7B,CAAC"}

package/dist/esm/api/context.js

@@ -6,6 +6,7 @@ export const createRequestContext = async (input) => {
         req: {
             headers: input.headers,
             cookies: input.cookies ?? {},
+            ip: input.ip,
         },
         res: input.res,
         getUser() {

package/dist/esm/api/context.js.map

@@ -1 +1 @@
-{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/api/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAiC1C,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,EACvC,KAA+B,EACD,EAAE;IAChC,MAAM,GAAG,GAAwB;QAC/B,GAAG,EAAE;YACH,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;SAC7B;QACD,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,OAAO;YACL,OAAO,EAAuB,CAAC;QACjC,CAAC;KACF,CAAC;IAEF,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,sBAAsB,GAAG,KAAK,CAAC;IAEnC,OAAO;QACL,GAAG,GAAG;QACN,IAAI;QACJ,OAAO;YACL,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,aAAa,CAAC,eAAe,CAAC,CAAC;YACjC,CAAC;YAED,IAAI,CAAC,sBAAsB,EAAE,CAAC;gBAC5B,MAAM,CAAC,QAAQ,CAAC,wBAAwB,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;gBAChE,sBAAsB,GAAG,IAAI,CAAC;YAChC,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../../../src/api/context.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAC9C,OAAO,EAAE,MAAM,EAAE,MAAM,eAAe,CAAC;AACvC,OAAO,EAAE,OAAO,EAAE,MAAM,iBAAiB,CAAC;AAmC1C,MAAM,CAAC,MAAM,oBAAoB,GAAG,KAAK,EACvC,KAA+B,EACD,EAAE;IAChC,MAAM,GAAG,GAAwB;QAC/B,GAAG,EAAE;YACH,OAAO,EAAE,KAAK,CAAC,OAAO;YACtB,OAAO,EAAE,KAAK,CAAC,OAAO,IAAI,EAAE;YAC5B,EAAE,EAAE,KAAK,CAAC,EAAE;SACb;QACD,GAAG,EAAE,KAAK,CAAC,GAAG;QACd,OAAO;YACL,OAAO,EAAuB,CAAC;QACjC,CAAC;KACF,CAAC;IAEF,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,GAAG,CAAC,CAAC;IAChC,IAAI,sBAAsB,GAAG,KAAK,CAAC;IAEnC,OAAO;QACL,GAAG,GAAG;QACN,IAAI;QACJ,OAAO;YACL,IAAI,CAAC,IAAI,EAAE,CAAC;gBACV,aAAa,CAAC,eAAe,CAAC,CAAC;YACjC,CAAC;YAED,IAAI,CAAC,sBAAsB,EAAE,CAAC;gBAC5B,MAAM,CAAC,QAAQ,CAAC,wBAAwB,EAAE,EAAE,MAAM,EAAE,IAAI,CAAC,GAAG,EAAE,CAAC,CAAC;gBAChE,sBAAsB,GAAG,IAAI,CAAC;YAChC,CAAC;YAED,OAAO,IAAI,CAAC;QACd,CAAC;KACF,CAAC;AACJ,CAAC,CAAC"}

package/dist/esm/api/operations/apiEventLog.d.ts

@@ -0,0 +1,25 @@
+import type { EventLogJsonValue } from '../../eventLog/index.js';
+import type { RakunRequestContext } from '../context.js';
+import type { AnyRakunOperation } from './types.js';
+export declare const setApiErrorEventData: (ctx: RakunRequestContext | undefined, data: Record<string, EventLogJsonValue>) => void;
+export declare const setApiSuccessEventData: (ctx: RakunRequestContext, data: Record<string, EventLogJsonValue>) => void;
+export type ApiErrorLogInput = {
+    name: string;
+    operation?: Pick<AnyRakunOperation, 'kind' | 'method'>;
+    ctx?: RakunRequestContext;
+    error: unknown;
+    statusCode?: number;
+    /**
+     * Marks the outer API adapter boundary. It clears propagation deduplication
+     * so a reused Error object can still be recorded by a later request.
+     */
+    boundary?: boolean;
+};
+export declare const recordApiError: ({ name, operation, ctx, error, statusCode, boundary, }: ApiErrorLogInput) => Promise<void>;
+export type ApiOperationSuccessLogInput = {
+    name: string;
+    operation: Pick<AnyRakunOperation, 'kind' | 'method'>;
+    ctx: RakunRequestContext;
+};
+export declare const recordApiOperationSuccess: ({ name, operation, ctx, }: ApiOperationSuccessLogInput) => Promise<void>;
+//# sourceMappingURL=apiEventLog.d.ts.map

package/dist/esm/api/operations/apiEventLog.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"apiEventLog.d.ts","sourceRoot":"","sources":["../../../../src/api/operations/apiEventLog.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAA;AACvD,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,YAAY,CAAA;AAErD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAA;AAYhD,eAAO,MAAM,oBAAoB,GAC/B,KAAK,mBAAmB,GAAG,SAAS,EACpC,MAAM,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,SAGxC,CAAA;AAED,eAAO,MAAM,sBAAsB,GACjC,KAAK,mBAAmB,EACxB,MAAM,MAAM,CAAC,MAAM,EAAE,iBAAiB,CAAC,SAGxC,CAAA;AAgCD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,CAAC,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAA;IACtD,GAAG,CAAC,EAAE,mBAAmB,CAAA;IACzB,KAAK,EAAE,OAAO,CAAA;IACd,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB;;;OAGG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB,CAAA;AAED,eAAO,MAAM,cAAc,GAAU,wDAOlC,gBAAgB,KAAG,OAAO,CAAC,IAAI,CAqDjC,CAAA;AAED,MAAM,MAAM,2BAA2B,GAAG;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,SAAS,EAAE,IAAI,CAAC,iBAAiB,EAAE,MAAM,GAAG,QAAQ,CAAC,CAAA;IACrD,GAAG,EAAE,mBAAmB,CAAA;CACzB,CAAA;AAED,eAAO,MAAM,yBAAyB,GAAU,2BAI7C,2BAA2B,KAAG,OAAO,CAAC,IAAI,CA0C5C,CAAA"}

package/dist/esm/api/operations/apiEventLog.js

@@ -0,0 +1,121 @@
+import { getEventLogService, hasEventLogService } from '../../eventLog/index.js';
+import { getAppErrorShape, getAppErrorStatusCode } from '../../lib/errors/index.js';
+import { Logger } from '../../lib/Logger.js';
+const loggedApiErrors = new WeakSet();
+const apiErrorEventData = new WeakMap();
+const apiSuccessEventData = new WeakMap();
+export const setApiErrorEventData = (ctx, data) => {
+    if (ctx)
+        apiErrorEventData.set(ctx, data);
+};
+export const setApiSuccessEventData = (ctx, data) => {
+    apiSuccessEventData.set(ctx, data);
+};
+const getHeaderValue = (headers, name) => {
+    const value = headers?.[name];
+    return Array.isArray(value) ? value[0] : value;
+};
+const getCorrelationId = (ctx) => {
+    const headers = ctx?.req?.headers;
+    return getHeaderValue(headers, 'x-correlation-id') ?? getHeaderValue(headers, 'x-request-id');
+};
+const getErrorName = (error) => {
+    if (error instanceof Error && error.name.trim()) {
+        return error.name;
+    }
+    return undefined;
+};
+const isObjectError = (error) => (typeof error === 'object' && error !== null) || typeof error === 'function';
+const getActor = (ctx) => ctx?.user?._id
+    ? { type: 'manager-user', id: String(ctx.user._id) }
+    : { type: 'anonymous' };
+export const recordApiError = async ({ name, operation, ctx, error, statusCode, boundary = false, }) => {
+    if (isObjectError(error) && loggedApiErrors.has(error)) {
+        if (boundary) {
+            loggedApiErrors.delete(error);
+        }
+        return;
+    }
+    const appError = getAppErrorShape(error);
+    const resolvedStatusCode = statusCode ?? getAppErrorStatusCode(error) ?? 500;
+    const errorName = appError ? undefined : getErrorName(error);
+    const contextualData = ctx ? apiErrorEventData.get(ctx) : undefined;
+    if (ctx)
+        apiErrorEventData.delete(ctx);
+    if (!hasEventLogService()) {
+        Logger?.error?.('API error could not be persisted because the event log is not initialized', {
+            operation: name,
+            statusCode: resolvedStatusCode,
+        });
+        return;
+    }
+    try {
+        await getEventLogService().record({
+            type: 'api.operation.failed',
+            category: 'api',
+            severity: resolvedStatusCode >= 500 ? 'error' : 'warning',
+            outcome: 'failure',
+            source: '@rakun-kit/core/api',
+            correlationId: getCorrelationId(ctx),
+            actor: getActor(ctx),
+            resource: { type: 'api-operation', id: name },
+            tags: ['api', 'error', ...(operation ? [operation.kind] : [])],
+            data: {
+                operation: name,
+                statusCode: resolvedStatusCode,
+                ...(operation ? { kind: operation.kind, method: operation.method } : {}),
+                ...(appError ? { errorKey: appError.key } : {}),
+                ...(errorName ? { errorName } : {}),
+                ...(contextualData ? { context: contextualData } : {}),
+            },
+        });
+        if (isObjectError(error) && !boundary) {
+            loggedApiErrors.add(error);
+        }
+    }
+    catch (logError) {
+        Logger?.error?.('API error event could not be persisted', {
+            operation: name,
+            statusCode: resolvedStatusCode,
+            error: logError,
+        });
+    }
+};
+export const recordApiOperationSuccess = async ({ name, operation, ctx, }) => {
+    if (operation.kind !== 'mutation') {
+        return;
+    }
+    const contextualData = apiSuccessEventData.get(ctx);
+    apiSuccessEventData.delete(ctx);
+    if (!hasEventLogService()) {
+        Logger?.error?.('API mutation success could not be persisted because the event log is not initialized', { operation: name });
+        return;
+    }
+    try {
+        const namespace = name.split('.')[0] || 'api';
+        await getEventLogService().record({
+            type: `${name}.succeeded`,
+            category: 'api',
+            severity: 'info',
+            outcome: 'success',
+            source: '@rakun-kit/core/api',
+            correlationId: getCorrelationId(ctx),
+            actor: getActor(ctx),
+            resource: { type: 'api-operation', id: name },
+            tags: ['api', 'mutation', 'success', namespace],
+            data: {
+                operation: name,
+                kind: operation.kind,
+                method: operation.method,
+                ...(contextualData ? { context: contextualData } : {}),
+            },
+        });
+    }
+    catch (error) {
+        Logger?.error?.('API mutation success event could not be persisted', {
+            operation: name,
+            error,
+        });
+    }
+};
+//# sourceMappingURL=apiEventLog.js.map

package/dist/esm/api/operations/apiEventLog.js.map

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