@elqnt/notifications 1.0.0 → 1.1.0

package/README.md

@@ -0,0 +1,56 @@
+# @elqnt/notifications
+
+Outbound notification primitives for the Eloquent platform. Today: sending a
+pre-rendered notification email through the API Gateway. Fully typed, zero `any`.
+
+> **Building a custom app / using an AI coding agent?** Read [`SKILL.md`](./SKILL.md)
+> — the full agent guide: the one-way architecture (intent → app hook → `useEmail`
+> → gateway → integrations service), the gateway-token flow, and the exact spec of
+> the hook (`useEmail` → `send`). It ships in the package, so the contract is this
+> package's own `.d.ts` — your code type-checks against it.
+
+## Installation
+
+```bash
+pnpm add @elqnt/notifications
+```
+
+## Quick Start
+
+```typescript
+import { useEmail } from "@elqnt/notifications/hooks";
+
+const { loading, error, send } = useEmail({ baseUrl: apiGatewayUrl, orgId });
+
+const res = await send({
+  to: ["user@example.com"],
+  subject: "Your report is ready",
+  body: "<p>Hi — your weekly report is attached.</p>", // already rendered
+});
+// res: SendEmailResponse | null  (null on error → check `error`)
+```
+
+## Hook
+
+### `useEmail(options)`
+
+```typescript
+const {
+  loading,  // boolean
+  error,    // string | null
+  send,     // (request: SendEmailRequest) => Promise<SendEmailResponse | null>
+} = useEmail({ baseUrl, orgId });
+```
+
+`send` posts to `POST /api/v1/email/send` (gateway → integrations service). It
+**never throws**: on failure it returns `null` and sets `error`.
+
+## Types
+
+```typescript
+import type { UseEmailOptions, UseEmailReturn } from "@elqnt/notifications/hooks";
+import type { SendEmailRequest, SendEmailResponse } from "@elqnt/notifications/models";
+```
+
+The root `@elqnt/notifications` re-exports the model types only (for SSR/type
+imports). The hook is reached **only** via `@elqnt/notifications/hooks`.

package/SKILL.md

@@ -0,0 +1,328 @@
+---
+name: notifications
+description: Send notification emails from a custom frontend on the Eloquent platform using the @elqnt/notifications hooks. Covers the one true path (custom app → useEmail hook → API Gateway → integrations Go service), the gateway-token/secret flow, and the EXACT input/output spec of the hook (useEmail — send) plus all types.
+---
+
+# Notifications — Sending Email from a Custom Frontend
+
+Eloquent's **notifications** package wraps the platform's outbound notification
+surface. Today it exposes **one** thing: sending a **pre-rendered notification
+email** through the API Gateway to the integrations service. This skill is only
+about driving that through the `@elqnt/notifications` package.
+
+> Package is `@elqnt/notifications`. It exports exactly one hook: `useEmail`.
+> The body you send is **already rendered** — `{ to, subject, body }`. The
+> package does not template, queue, schedule, or fan-out; for bulk/newsletter
+> flows the gateway has separate routes (`/api/v1/email/bulk-send`,
+> `/api/v1/newsletter/...`) not yet wrapped by this package.
+
+---
+
+## ⛔ The contract — read this before writing any code
+
+This skill ships **inside the package**, so the contract is not a separate file
+to keep in sync — it **is** the package's own published type declarations
+(`@elqnt/notifications` → `dist/**/*.d.ts`). Because your app *imports the real
+hook*, the TypeScript compiler enforces the contract for you: a wrong param or a
+misused return value won't compile.
+
+The single source of truth, in order:
+
+1. `import { useEmail } from "@elqnt/notifications/hooks"` — the only hook.
+2. `import type { UseEmailOptions, UseEmailReturn } from "@elqnt/notifications/hooks"`
+   — the **named, exact** surface of the hook (every method, its params, its
+   return type). The table below is a human-readable mirror of these.
+3. `import type { SendEmailRequest, SendEmailResponse } from "@elqnt/notifications/models"`
+   — the request/response DTOs. (Also re-exported from the root
+   `@elqnt/notifications` for type-only/SSR imports.)
+
+**Rules (do not drift):**
+
+1. **Use only the exported hook** and only the method it exposes (`send`). Do
+   **not** invent hooks, methods, params, or return shapes — if it's not on
+   `UseEmailReturn`, it doesn't exist.
+2. **Let the compiler check you.** Build with `tsc`; never `as any` /
+   `@ts-ignore` your way around the hook's types.
+3. **Never bypass the hook.** No `fetch`/`axios` to `/api/v1/email/...`, no NATS,
+   no direct service calls.
+4. **Wrap, don't scatter.** The hook is imported in exactly one app file
+   (`hooks/use-<domain>.ts`); see ["The domain layer"](#the-domain-layer).
+5. **`body` is already rendered.** The package sends what you give it; rendering
+   HTML/markdown is the app's job.
+
+The prose/table below explains the method; the package's shipped `.d.ts` is what
+your code type-checks against.
+
+---
+
+## Architecture — the one and only path
+
+A component **never** calls the package hook directly. It only sees your **domain
+intent** (e.g. "notify these users"), served by your **app hook**, which is the
+*only* place that wraps `useEmail`.
+
+```
+┌──────────────────────────────────────────────────────────────────────────────┐
+│  YOUR CUSTOM APP (Next.js / React)                                             │
+│                                                                                │
+│  SSR layout: read API_GATEWAY_URL_PUBLIC (request-time) + ORG_ID               │
+│       └─► AppConfigProvider { apiGatewayUrl, orgId }                           │
+│                                                                                │
+│  components/*            ── trigger "send a notification" intents              │
+│         │                                                                       │
+│         ▼                                                                       │
+│  hooks/use-notify.ts     ── app hook: the only file importing @elqnt/notifications│
+│         │                                                                       │
+│         ▼                                                                       │
+│  useEmail               (@elqnt/notifications/hooks)                           │
+│         │                                                                       │
+│         ▼                                                                       │
+│  browserApiRequest      (@elqnt/api-client/browser)                           │
+│         │  getGatewayToken() ⇒ GET /api/gateway-token (mint HS256 JWT, JWT_SECRET)│
+│         │  attaches: Authorization: Bearer <jwt>, X-Org-ID, X-User-ID, X-Product│
+└─────────┼──────────────────────────────────────────────────────────────────────┘
+          ▼
+   ┌─────────────────┐   verify JWT, stamp X-Org-ID/X-Product, route match
+   │   API GATEWAY   │   POST /api/v1/email/send → integrations svc
+   └───────┬─────────┘
+           ▼
+   ┌─────────────────┐   renders nothing — sends the pre-rendered body
+   │ integrations(Go)│   via the configured email provider
+   └─────────────────┘
+```
+
+Rules: the frontend **never** calls the integrations service directly and
+**never** touches NATS. Every call is HTTP through the gateway carrying an org id
++ gateway token. And **components never import `@elqnt/notifications`** — only the
+app hook does.
+
+---
+
+## The gateway token (the secret) — how the custom app gets it
+
+Every request to the gateway needs `Authorization: Bearer <token>`: a short-lived
+**HS256 JWT** signed with the shared **gateway secret**. You never hardcode it.
+
+### Browser flow (what the hook uses)
+
+The hook → `browserApiRequest` → `getGatewayToken()` internally. You do **not**
+pass a token to the hook. `getGatewayToken()` (from `@elqnt/api-client/browser`)
+by default does:
+
+```
+fetch("/api/gateway-token")   ⇒  { token, expiresIn }
+```
+
+So your custom app must expose a **`/api/gateway-token` route** that mints the JWT
+server-side (the secret stays on the server, never reaches the browser). The
+client caches the token and refreshes ~5 min before expiry.
+
+```ts
+// app/api/gateway-token/route.ts  (Next.js route handler — server only)
+import { NextResponse } from "next/server";
+import * as jose from "jose";
+
+export async function GET() {
+  const secret = new TextEncoder().encode(process.env.JWT_SECRET!);  // SAME secret the gateway validates with
+  const token = await new jose.SignJWT({
+    org_id:  process.env.ORG_ID!,
+    user_id: "system",
+    email:   "system@my-app.com",
+    role:    "system",
+    scopes:  ["write:notifications"],   // OR-matched against the route's required scopes
+    product: "my-product",              // gateway resolves product from THIS claim first
+  })
+    .setProtectedHeader({ alg: "HS256" })
+    .setIssuedAt()
+    .setIssuer("eloquent-gateway")     // must match gateway JWT_ISSUER
+    .setAudience("eloquent-api")       // must match gateway JWT_AUDIENCE
+    .setExpirationTime("1h")
+    .sign(secret);
+
+  return NextResponse.json({ token, expiresIn: 3600 });
+}
+```
+
+> The gateway re-stamps `X-Org-ID` / `X-User-ID` / `X-Product` from the **signed
+> JWT claims** before proxying, so a forged header can't override the token — the
+> JWT is authoritative.
+
+Override the token source (mobile/native, or a non-default URL) once at startup:
+
+```ts
+import { configureAuth } from "@elqnt/api-client/browser";
+configureAuth(async () => myTokenProvider());     // URL string or async () => token|null
+```
+
+### Server flow (server actions / SSR)
+
+The `useEmail` hook is **browser-only** (`"use client"`). For SSR/server actions,
+send via `@elqnt/api-client/server`'s `createServerClient` (mints the JWT itself
+with `JWT_SECRET` — no `/api/gateway-token` hop) and POST `/api/v1/email/send`
+directly.
+
+```ts
+import { createServerClient } from "@elqnt/api-client/server";
+
+const client = createServerClient({
+  gatewayUrl: process.env.API_GATEWAY_URL_INTERNAL!,  // in-cluster gateway URL (server-side)
+  jwtSecret:  process.env.JWT_SECRET!,                // the shared gateway secret
+  defaultProduct: "my-product",                        // gateway reads product from the JWT claim first
+  defaultScopes: ["read", "write"],
+});
+
+await client.post("/api/v1/email/send",
+  { to: ["user@example.com"], subject: "Welcome", body: "<p>Hi</p>" },
+  { orgId });
+```
+
+### Env vars
+
+| Var | Used by | Purpose |
+|---|---|---|
+| `JWT_SECRET` | `/api/gateway-token` route + `createServerClient` | sign the gateway JWT (same value the gateway validates with) |
+| `API_GATEWAY_URL_INTERNAL` | `createServerClient` `gatewayUrl` | in-cluster gateway URL (server) |
+| `API_GATEWAY_URL_PUBLIC` | SSR layout → `AppConfigProvider` → browser `baseUrl` | public gateway URL, read **at request time** (not `NEXT_PUBLIC_*`) |
+| `ORG_ID` | token route / app config | the org all requests are scoped to |
+
+### Headers the API layer sets per request
+
+| From hook option | Header |
+|---|---|
+| auto token | `Authorization: Bearer <token>` |
+| `orgId` | `X-Org-ID` |
+| `userId` | `X-User-ID` |
+| `userEmail` | `X-User-Email` |
+| `product` (default `"eloquent"`) | `X-Product` |
+
+---
+
+## Hook options
+
+There is **no provider/context** in this package. You pass options into the hook
+call. `UseEmailOptions` is the shared `ApiClientOptions`:
+
+```ts
+interface ApiClientOptions {
+  baseUrl: string;     // API Gateway base URL — required
+  orgId: string;       // required → X-Org-ID
+  userId?: string;     // → X-User-ID
+  userEmail?: string;  // → X-User-Email
+  product?: string;    // → X-Product, defaults to "eloquent"
+  headers?: Record<string, string>;
+}
+
+type UseEmailOptions = ApiClientOptions;
+```
+
+> **Imperative, not auto-fetching.** The hook does **not** send anything on
+> mount. You call `send(...)` on demand. The hook exposes `loading` / `error`
+> flags. On failure `send` returns `null` and sets `error` — it does **not**
+> throw.
+
+---
+
+## Hook: `useEmail`
+
+```ts
+import { useEmail } from "@elqnt/notifications/hooks";
+
+const email = useEmail({ baseUrl, orgId, product: "my-product" });
+```
+
+Returns `{ loading, error, send }` (`UseEmailReturn`):
+
+| Member | Signature | Resolves to | Endpoint |
+|---|---|---|---|
+| `loading` | `boolean` | — | — |
+| `error` | `string \| null` | — | — |
+| `send` | `(request: SendEmailRequest) => Promise<SendEmailResponse \| null>` | `null` on error (sets `error`) | `POST /api/v1/email/send` |
+
+```ts
+const res = await email.send({
+  to: ["user@example.com", "ops@example.com"],
+  subject: "Your report is ready",
+  body: "<p>Hi — your weekly report is attached.</p>",   // already rendered
+});
+if (!res || !res.success) {
+  // email.error is set; surface it
+}
+```
+
+---
+
+## Types (`@elqnt/notifications/models`)
+
+> Generated from Go via `tygo generate`. Never edit `models/email.ts` manually.
+
+```ts
+/** Request for sending a pre-rendered notification email. */
+interface SendEmailRequest {
+  to: string[];      // one or more recipient addresses
+  subject: string;
+  body: string;      // already-rendered HTML/text
+}
+
+/** Response from sending an email. */
+interface SendEmailResponse {
+  success: boolean;
+  message?: string;  // provider/error detail when present
+}
+```
+
+---
+
+## The domain layer
+
+Wrap the hook in **one** app file; components speak your intent, not
+`SendEmailRequest`.
+
+```ts
+// hooks/use-notify.ts
+"use client";
+import { useEmail } from "@elqnt/notifications/hooks";
+import { useAppConfig } from "@/contexts/app-config-context";
+
+export function useNotify() {
+  const { apiGatewayUrl, orgId } = useAppConfig();
+  const email = useEmail({ baseUrl: apiGatewayUrl, orgId, product: "my-product" });
+
+  return {
+    loading: email.loading,
+    error: email.error,
+    async notifyReportReady(to: string[], reportName: string): Promise<boolean> {
+      const res = await email.send({
+        to,
+        subject: `Your report "${reportName}" is ready`,
+        body: renderReportEmail(reportName),   // your app renders the body
+      });
+      return !!res?.success;
+    },
+  };
+}
+
+export type UseNotifyReturn = ReturnType<typeof useNotify>;
+```
+
+`{ apiGatewayUrl, orgId }` come from an `AppConfigProvider` fed by SSR
+(`API_GATEWAY_URL_PUBLIC` read at request time — never a `NEXT_PUBLIC_*` var).
+See the `@elqnt/entity` SKILL.md for the full `AppConfigProvider` pattern.
+
+---
+
+## Gotchas
+
+- **One hook, one method.** Only `useEmail().send`. Bulk-send and newsletter
+  flows exist on the gateway but are **not** wrapped here yet — don't invent
+  `sendBulk`/`useNewsletter`.
+- **`body` is pre-rendered.** The package/service does not template. Render the
+  HTML/text in your app before calling `send`.
+- **`send` doesn't throw.** It returns `null` and sets `error` on failure (and a
+  non-null result may still have `success: false` — check it).
+- **Hook is browser-only** (`"use client"`). For SSR/server actions, POST
+  `/api/v1/email/send` via `createServerClient` — not the hook.
+- **Root import is models-only.** `@elqnt/notifications` re-exports only the
+  types; the hook is reached **only** via `@elqnt/notifications/hooks`. Importing
+  the hook from the root would drag `"use client"` into server components.
+- **`product` matters.** The gateway resolves product from the **JWT claim**
+  (server) and `X-Product` (browser). It scopes which org/provider config is used.

package/dist/hooks/index.d.mts

@@ -1,11 +1,31 @@
+import { ApiClientOptions } from '@elqnt/api-client/browser';
 import { SendEmailRequest, SendEmailResponse } from '../models/index.mjs';
 
-interface UseEmailOptions {
-    baseUrl: string;
-    orgId: string;
-}
-declare function useEmail(options: UseEmailOptions): {
+/**
+ * Options for {@link useEmail}. Extends the shared gateway client options
+ * (`baseUrl`, `orgId`, `product`, …) from `@elqnt/api-client`.
+ */
+type UseEmailOptions = ApiClientOptions;
+/**
+ * The exact, named contract of {@link useEmail}. Consumers type-check against
+ * this published interface — it can't drift from the implementation.
+ *
+ * Per the SDK hook contract: `{ loading, error, ...methods }`; methods are
+ * `async (...args) => Promise<Result>`, call on demand (no fetch-on-mount), and
+ * never throw — on failure they resolve to a documented default and set `error`.
+ */
+interface UseEmailReturn {
+    /** True while a `send` request is in flight. */
+    loading: boolean;
+    /** Last error message, or `null`. Cleared at the start of each `send`. */
+    error: string | null;
+    /**
+     * Send a pre-rendered notification email.
+     * `POST /api/v1/email/send` (gateway → integrations service).
+     * Resolves to the response on success, or `null` on failure (sets `error`).
+     */
     send: (request: SendEmailRequest) => Promise<SendEmailResponse | null>;
-};
+}
+declare function useEmail(options: UseEmailOptions): UseEmailReturn;
 
-export { useEmail };
+export { type UseEmailOptions, type UseEmailReturn, useEmail };

package/dist/hooks/index.d.ts

@@ -1,11 +1,31 @@
+import { ApiClientOptions } from '@elqnt/api-client/browser';
 import { SendEmailRequest, SendEmailResponse } from '../models/index.js';
 
-interface UseEmailOptions {
-    baseUrl: string;
-    orgId: string;
-}
-declare function useEmail(options: UseEmailOptions): {
+/**
+ * Options for {@link useEmail}. Extends the shared gateway client options
+ * (`baseUrl`, `orgId`, `product`, …) from `@elqnt/api-client`.
+ */
+type UseEmailOptions = ApiClientOptions;
+/**
+ * The exact, named contract of {@link useEmail}. Consumers type-check against
+ * this published interface — it can't drift from the implementation.
+ *
+ * Per the SDK hook contract: `{ loading, error, ...methods }`; methods are
+ * `async (...args) => Promise<Result>`, call on demand (no fetch-on-mount), and
+ * never throw — on failure they resolve to a documented default and set `error`.
+ */
+interface UseEmailReturn {
+    /** True while a `send` request is in flight. */
+    loading: boolean;
+    /** Last error message, or `null`. Cleared at the start of each `send`. */
+    error: string | null;
+    /**
+     * Send a pre-rendered notification email.
+     * `POST /api/v1/email/send` (gateway → integrations service).
+     * Resolves to the response on success, or `null` on failure (sets `error`).
+     */
     send: (request: SendEmailRequest) => Promise<SendEmailResponse | null>;
-};
+}
+declare function useEmail(options: UseEmailOptions): UseEmailReturn;
 
-export { useEmail };
+export { type UseEmailOptions, type UseEmailReturn, useEmail };

package/dist/hooks/index.js

@@ -1,9 +1,38 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
-"use client";
+"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }"use client";
 
+// hooks/use-email.ts
+var _react = require('react');
+var _browser = require('@elqnt/api-client/browser');
+function useEmail(options) {
+  const [loading, setLoading] = _react.useState.call(void 0, false);
+  const [error, setError] = _react.useState.call(void 0, null);
+  const apiOptions = _react.useMemo.call(void 0, () => ({ ...options }), [options]);
+  const send = _react.useCallback.call(void 0, 
+    async (request) => {
+      setLoading(true);
+      setError(null);
+      try {
+        const response = await _browser.browserApiRequest.call(void 0, 
+          "/api/v1/email/send",
+          {
+            method: "POST",
+            body: request,
+            ...apiOptions
+          }
+        );
+        return _nullishCoalesce(response.data, () => ( null));
+      } catch (e) {
+        setError(e instanceof Error ? e.message : "Failed to send email");
+        return null;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [apiOptions]
+  );
+  return { loading, error, send };
+}
 
-var _chunkE6ORNZJXjs = require('../chunk-E6ORNZJX.js');
 
-
-exports.useEmail = _chunkE6ORNZJXjs.useEmail;
+exports.useEmail = useEmail;
 //# sourceMappingURL=index.js.map

package/dist/hooks/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/eloquent-packages/eloquent-packages/packages/notifications/dist/hooks/index.js"],"names":[],"mappings":"AAAA,qFAAY;AACZ,YAAY;AACZ;AACE;AACF,uDAA6B;AAC7B;AACE;AACF,6CAAC","file":"/home/runner/work/eloquent-packages/eloquent-packages/packages/notifications/dist/hooks/index.js"}
+{"version":3,"sources":["/home/runner/work/eloquent/eloquent/packages/@elqnt/notifications/dist/hooks/index.js","../../hooks/use-email.ts"],"names":[],"mappings":"AAAA,yLAAY;AACZ;AACA;ACAA,8BAA+C;AAC/C,oDAAkC;AA+B3B,SAAS,QAAA,CAAS,OAAA,EAA0C;AACjE,EAAA,MAAM,CAAC,OAAA,EAAS,UAAU,EAAA,EAAI,6BAAA,KAAc,CAAA;AAC5C,EAAA,MAAM,CAAC,KAAA,EAAO,QAAQ,EAAA,EAAI,6BAAA,IAA4B,CAAA;AAEtD,EAAA,MAAM,WAAA,EAAa,4BAAA,CAA0B,EAAA,GAAA,CAAO,EAAE,GAAG,QAAQ,CAAA,CAAA,EAAI,CAAC,OAAO,CAAC,CAAA;AAE9E,EAAA,MAAM,KAAA,EAAO,gCAAA;AAAA,IACX,MAAA,CAAO,OAAA,EAAA,GAAiE;AACtE,MAAA,UAAA,CAAW,IAAI,CAAA;AACf,MAAA,QAAA,CAAS,IAAI,CAAA;AACb,MAAA,IAAI;AACF,QAAA,MAAM,SAAA,EAAW,MAAM,wCAAA;AAAA,UACrB,oBAAA;AAAA,UACA;AAAA,YACE,MAAA,EAAQ,MAAA;AAAA,YACR,IAAA,EAAM,OAAA;AAAA,YACN,GAAG;AAAA,UACL;AAAA,QACF,CAAA;AACA,QAAA,wBAAO,QAAA,CAAS,IAAA,UAAQ,MAAA;AAAA,MAC1B,EAAA,MAAA,CAAS,CAAA,EAAG;AACV,QAAA,QAAA,CAAS,EAAA,WAAa,MAAA,EAAQ,CAAA,CAAE,QAAA,EAAU,sBAAsB,CAAA;AAChE,QAAA,OAAO,IAAA;AAAA,MACT,EAAA,QAAE;AACA,QAAA,UAAA,CAAW,KAAK,CAAA;AAAA,MAClB;AAAA,IACF,CAAA;AAAA,IACA,CAAC,UAAU;AAAA,EACb,CAAA;AAEA,EAAA,OAAO,EAAE,OAAA,EAAS,KAAA,EAAO,KAAK,CAAA;AAChC;AD/BA;AACE;AACF,4BAAC","file":"/home/runner/work/eloquent/eloquent/packages/@elqnt/notifications/dist/hooks/index.js","sourcesContent":[null,"\"use client\";\n\nimport { useCallback, useMemo, useState } from \"react\";\nimport { browserApiRequest } from \"@elqnt/api-client/browser\";\nimport type { ApiClientOptions } from \"@elqnt/api-client/browser\";\nimport type { SendEmailRequest, SendEmailResponse } from \"../models\";\n\n/**\n * Options for {@link useEmail}. Extends the shared gateway client options\n * (`baseUrl`, `orgId`, `product`, …) from `@elqnt/api-client`.\n */\nexport type UseEmailOptions = ApiClientOptions;\n\n/**\n * The exact, named contract of {@link useEmail}. Consumers type-check against\n * this published interface — it can't drift from the implementation.\n *\n * Per the SDK hook contract: `{ loading, error, ...methods }`; methods are\n * `async (...args) => Promise<Result>`, call on demand (no fetch-on-mount), and\n * never throw — on failure they resolve to a documented default and set `error`.\n */\nexport interface UseEmailReturn {\n  /** True while a `send` request is in flight. */\n  loading: boolean;\n  /** Last error message, or `null`. Cleared at the start of each `send`. */\n  error: string | null;\n  /**\n   * Send a pre-rendered notification email.\n   * `POST /api/v1/email/send` (gateway → integrations service).\n   * Resolves to the response on success, or `null` on failure (sets `error`).\n   */\n  send: (request: SendEmailRequest) => Promise<SendEmailResponse | null>;\n}\n\nexport function useEmail(options: UseEmailOptions): UseEmailReturn {\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<string | null>(null);\n\n  const apiOptions = useMemo<ApiClientOptions>(() => ({ ...options }), [options]);\n\n  const send = useCallback(\n    async (request: SendEmailRequest): Promise<SendEmailResponse | null> => {\n      setLoading(true);\n      setError(null);\n      try {\n        const response = await browserApiRequest<SendEmailResponse>(\n          \"/api/v1/email/send\",\n          {\n            method: \"POST\",\n            body: request,\n            ...apiOptions,\n          }\n        );\n        return response.data ?? null;\n      } catch (e) {\n        setError(e instanceof Error ? e.message : \"Failed to send email\");\n        return null;\n      } finally {\n        setLoading(false);\n      }\n    },\n    [apiOptions]\n  );\n\n  return { loading, error, send };\n}\n"]}

package/dist/hooks/index.mjs

@@ -1,8 +1,37 @@
 "use client";
-"use client";
-import {
-  useEmail
-} from "../chunk-OPXXF4IO.mjs";
+
+// hooks/use-email.ts
+import { useCallback, useMemo, useState } from "react";
+import { browserApiRequest } from "@elqnt/api-client/browser";
+function useEmail(options) {
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState(null);
+  const apiOptions = useMemo(() => ({ ...options }), [options]);
+  const send = useCallback(
+    async (request) => {
+      setLoading(true);
+      setError(null);
+      try {
+        const response = await browserApiRequest(
+          "/api/v1/email/send",
+          {
+            method: "POST",
+            body: request,
+            ...apiOptions
+          }
+        );
+        return response.data ?? null;
+      } catch (e) {
+        setError(e instanceof Error ? e.message : "Failed to send email");
+        return null;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [apiOptions]
+  );
+  return { loading, error, send };
+}
 export {
   useEmail
 };

package/dist/hooks/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}
+{"version":3,"sources":["../../hooks/use-email.ts"],"sourcesContent":["\"use client\";\n\nimport { useCallback, useMemo, useState } from \"react\";\nimport { browserApiRequest } from \"@elqnt/api-client/browser\";\nimport type { ApiClientOptions } from \"@elqnt/api-client/browser\";\nimport type { SendEmailRequest, SendEmailResponse } from \"../models\";\n\n/**\n * Options for {@link useEmail}. Extends the shared gateway client options\n * (`baseUrl`, `orgId`, `product`, …) from `@elqnt/api-client`.\n */\nexport type UseEmailOptions = ApiClientOptions;\n\n/**\n * The exact, named contract of {@link useEmail}. Consumers type-check against\n * this published interface — it can't drift from the implementation.\n *\n * Per the SDK hook contract: `{ loading, error, ...methods }`; methods are\n * `async (...args) => Promise<Result>`, call on demand (no fetch-on-mount), and\n * never throw — on failure they resolve to a documented default and set `error`.\n */\nexport interface UseEmailReturn {\n  /** True while a `send` request is in flight. */\n  loading: boolean;\n  /** Last error message, or `null`. Cleared at the start of each `send`. */\n  error: string | null;\n  /**\n   * Send a pre-rendered notification email.\n   * `POST /api/v1/email/send` (gateway → integrations service).\n   * Resolves to the response on success, or `null` on failure (sets `error`).\n   */\n  send: (request: SendEmailRequest) => Promise<SendEmailResponse | null>;\n}\n\nexport function useEmail(options: UseEmailOptions): UseEmailReturn {\n  const [loading, setLoading] = useState(false);\n  const [error, setError] = useState<string | null>(null);\n\n  const apiOptions = useMemo<ApiClientOptions>(() => ({ ...options }), [options]);\n\n  const send = useCallback(\n    async (request: SendEmailRequest): Promise<SendEmailResponse | null> => {\n      setLoading(true);\n      setError(null);\n      try {\n        const response = await browserApiRequest<SendEmailResponse>(\n          \"/api/v1/email/send\",\n          {\n            method: \"POST\",\n            body: request,\n            ...apiOptions,\n          }\n        );\n        return response.data ?? null;\n      } catch (e) {\n        setError(e instanceof Error ? e.message : \"Failed to send email\");\n        return null;\n      } finally {\n        setLoading(false);\n      }\n    },\n    [apiOptions]\n  );\n\n  return { loading, error, send };\n}\n"],"mappings":";;;AAEA,SAAS,aAAa,SAAS,gBAAgB;AAC/C,SAAS,yBAAyB;AA+B3B,SAAS,SAAS,SAA0C;AACjE,QAAM,CAAC,SAAS,UAAU,IAAI,SAAS,KAAK;AAC5C,QAAM,CAAC,OAAO,QAAQ,IAAI,SAAwB,IAAI;AAEtD,QAAM,aAAa,QAA0B,OAAO,EAAE,GAAG,QAAQ,IAAI,CAAC,OAAO,CAAC;AAE9E,QAAM,OAAO;AAAA,IACX,OAAO,YAAiE;AACtE,iBAAW,IAAI;AACf,eAAS,IAAI;AACb,UAAI;AACF,cAAM,WAAW,MAAM;AAAA,UACrB;AAAA,UACA;AAAA,YACE,QAAQ;AAAA,YACR,MAAM;AAAA,YACN,GAAG;AAAA,UACL;AAAA,QACF;AACA,eAAO,SAAS,QAAQ;AAAA,MAC1B,SAAS,GAAG;AACV,iBAAS,aAAa,QAAQ,EAAE,UAAU,sBAAsB;AAChE,eAAO;AAAA,MACT,UAAE;AACA,mBAAW,KAAK;AAAA,MAClB;AAAA,IACF;AAAA,IACA,CAAC,UAAU;AAAA,EACb;AAEA,SAAO,EAAE,SAAS,OAAO,KAAK;AAChC;","names":[]}

package/dist/index.d.mts

@@ -1,2 +1 @@
 export { SendEmailRequest, SendEmailResponse } from './models/index.mjs';
-export { useEmail } from './hooks/index.mjs';

package/dist/index.d.ts

@@ -1,2 +1 @@
 export { SendEmailRequest, SendEmailResponse } from './models/index.js';
-export { useEmail } from './hooks/index.js';

package/dist/index.js

@@ -1,8 +1 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true});"use client";
-
-
-var _chunkE6ORNZJXjs = require('./chunk-E6ORNZJX.js');
-
-
-exports.useEmail = _chunkE6ORNZJXjs.useEmail;
-//# sourceMappingURL=index.js.map
+"use strict";//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/eloquent-packages/eloquent-packages/packages/notifications/dist/index.js"],"names":[],"mappings":"AAAA,qFAAY;AACZ;AACE;AACF,sDAA4B;AAC5B;AACE;AACF,6CAAC","file":"/home/runner/work/eloquent-packages/eloquent-packages/packages/notifications/dist/index.js"}
+{"version":3,"sources":["/home/runner/work/eloquent/eloquent/packages/@elqnt/notifications/dist/index.js"],"names":[],"mappings":"AAAA","file":"/home/runner/work/eloquent/eloquent/packages/@elqnt/notifications/dist/index.js"}

package/dist/index.mjs

@@ -1,8 +1 @@
-"use client";
-import {
-  useEmail
-} from "./chunk-OPXXF4IO.mjs";
-export {
-  useEmail
-};
 //# sourceMappingURL=index.mjs.map

package/dist/models/index.js

@@ -1,2 +1 @@
-"use strict";"use client";
-//# sourceMappingURL=index.js.map
+"use strict";//# sourceMappingURL=index.js.map

package/dist/models/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["/home/runner/work/eloquent-packages/eloquent-packages/packages/notifications/dist/models/index.js"],"names":[],"mappings":"AAAA,yBAAY","file":"/home/runner/work/eloquent-packages/eloquent-packages/packages/notifications/dist/models/index.js"}
+{"version":3,"sources":["/home/runner/work/eloquent/eloquent/packages/@elqnt/notifications/dist/models/index.js"],"names":[],"mappings":"AAAA","file":"/home/runner/work/eloquent/eloquent/packages/@elqnt/notifications/dist/models/index.js"}

package/dist/models/index.mjs

@@ -1,2 +1 @@
-"use client";
 //# sourceMappingURL=index.mjs.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elqnt/notifications",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Notification infrastructure for Eloquent platform (email, push, SMS)",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -23,30 +23,31 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "SKILL.md"
   ],
-  "scripts": {
-    "build": "tsup",
-    "dev": "tsup --watch",
-    "clean": "rm -rf dist",
-    "typecheck": "tsc --noEmit"
-  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Blazi-Commerce/eloquent-packages.git",
     "directory": "packages/notifications"
   },
   "dependencies": {
-    "@elqnt/api-client": "^1.0.0"
+    "@elqnt/api-client": "2.2.0"
   },
   "peerDependencies": {
     "react": "^18.0.0 || ^19.0.0"
   },
   "devDependencies": {
-    "@elqnt/api-client": "^1.0.0",
     "@types/react": "^19.0.0",
     "react": "^19.0.0",
     "tsup": "^8.0.0",
-    "typescript": "^5.0.0"
+    "typescript": "^5.0.0",
+    "@elqnt/api-client": "2.2.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "dev": "tsup --watch",
+    "clean": "rm -rf dist",
+    "typecheck": "tsc --noEmit"
   }
-}
+}

package/dist/chunk-E6ORNZJX.js

@@ -1,36 +0,0 @@
-"use strict";Object.defineProperty(exports, "__esModule", {value: true}); function _nullishCoalesce(lhs, rhsFn) { if (lhs != null) { return lhs; } else { return rhsFn(); } }"use client";
-
-// hooks/use-email.ts
-var _react = require('react');
-var _browser = require('@elqnt/api-client/browser');
-function useEmail(options) {
-  const apiOptions = _react.useMemo.call(void 0, 
-    () => ({ baseUrl: options.baseUrl, orgId: options.orgId }),
-    [options.baseUrl, options.orgId]
-  );
-  const send = _react.useCallback.call(void 0, 
-    async (request) => {
-      try {
-        const response = await _browser.browserApiRequest.call(void 0, 
-          "/api/v1/email/send",
-          {
-            method: "POST",
-            body: request,
-            ...apiOptions
-          }
-        );
-        return _nullishCoalesce(response.data, () => ( null));
-      } catch (e) {
-        console.warn("Failed to send email notification");
-        return null;
-      }
-    },
-    [apiOptions]
-  );
-  return { send };
-}
-
-
-
-exports.useEmail = useEmail;
-//# sourceMappingURL=chunk-E6ORNZJX.js.map

package/dist/chunk-E6ORNZJX.js.map

@@ -1 +0,0 @@
-{"version":3,"sources":["/home/runner/work/eloquent-packages/eloquent-packages/packages/notifications/dist/chunk-E6ORNZJX.js","../hooks/use-email.ts"],"names":[],"mappings":"AAAA,yLAAY;AACZ;AACA;ACAA,8BAAqC;AACrC,oDAAkC;AAS3B,SAAS,QAAA,CAAS,OAAA,EAA0B;AACjD,EAAA,MAAM,WAAA,EAAa,4BAAA;AAAA,IACjB,CAAA,EAAA,GAAA,CAAO,EAAE,OAAA,EAAS,OAAA,CAAQ,OAAA,EAAS,KAAA,EAAO,OAAA,CAAQ,MAAM,CAAA,CAAA;AAAA,IACxD,CAAC,OAAA,CAAQ,OAAA,EAAS,OAAA,CAAQ,KAAK;AAAA,EACjC,CAAA;AAEA,EAAA,MAAM,KAAA,EAAO,gCAAA;AAAA,IACX,MAAA,CAAO,OAAA,EAAA,GAAiE;AACtE,MAAA,IAAI;AACF,QAAA,MAAM,SAAA,EAAW,MAAM,wCAAA;AAAA,UACrB,oBAAA;AAAA,UACA;AAAA,YACE,MAAA,EAAQ,MAAA;AAAA,YACR,IAAA,EAAM,OAAA;AAAA,YACN,GAAG;AAAA,UACL;AAAA,QACF,CAAA;AACA,QAAA,wBAAO,QAAA,CAAS,IAAA,UAAQ,MAAA;AAAA,MAC1B,EAAA,UAAQ;AACN,QAAA,OAAA,CAAQ,IAAA,CAAK,mCAAmC,CAAA;AAChD,QAAA,OAAO,IAAA;AAAA,MACT;AAAA,IACF,CAAA;AAAA,IACA,CAAC,UAAU;AAAA,EACb,CAAA;AAEA,EAAA,OAAO,EAAE,KAAK,CAAA;AAChB;ADRA;AACA;AACE;AACF,4BAAC","file":"/home/runner/work/eloquent-packages/eloquent-packages/packages/notifications/dist/chunk-E6ORNZJX.js","sourcesContent":[null,"\"use client\";\n\nimport { useCallback, useMemo } from \"react\";\nimport { browserApiRequest } from \"@elqnt/api-client/browser\";\nimport type { ApiClientOptions } from \"@elqnt/api-client/browser\";\nimport type { SendEmailRequest, SendEmailResponse } from \"../models\";\n\ninterface UseEmailOptions {\n  baseUrl: string;\n  orgId: string;\n}\n\nexport function useEmail(options: UseEmailOptions) {\n  const apiOptions = useMemo<ApiClientOptions>(\n    () => ({ baseUrl: options.baseUrl, orgId: options.orgId }),\n    [options.baseUrl, options.orgId]\n  );\n\n  const send = useCallback(\n    async (request: SendEmailRequest): Promise<SendEmailResponse | null> => {\n      try {\n        const response = await browserApiRequest<SendEmailResponse>(\n          \"/api/v1/email/send\",\n          {\n            method: \"POST\",\n            body: request,\n            ...apiOptions,\n          }\n        );\n        return response.data ?? null;\n      } catch {\n        console.warn(\"Failed to send email notification\");\n        return null;\n      }\n    },\n    [apiOptions]\n  );\n\n  return { send };\n}\n"]}

package/dist/chunk-OPXXF4IO.mjs

@@ -1,36 +0,0 @@
-"use client";
-
-// hooks/use-email.ts
-import { useCallback, useMemo } from "react";
-import { browserApiRequest } from "@elqnt/api-client/browser";
-function useEmail(options) {
-  const apiOptions = useMemo(
-    () => ({ baseUrl: options.baseUrl, orgId: options.orgId }),
-    [options.baseUrl, options.orgId]
-  );
-  const send = useCallback(
-    async (request) => {
-      try {
-        const response = await browserApiRequest(
-          "/api/v1/email/send",
-          {
-            method: "POST",
-            body: request,
-            ...apiOptions
-          }
-        );
-        return response.data ?? null;
-      } catch {
-        console.warn("Failed to send email notification");
-        return null;
-      }
-    },
-    [apiOptions]
-  );
-  return { send };
-}
-
-export {
-  useEmail
-};
-//# sourceMappingURL=chunk-OPXXF4IO.mjs.map

package/dist/chunk-OPXXF4IO.mjs.map

@@ -1 +0,0 @@
-{"version":3,"sources":["../hooks/use-email.ts"],"sourcesContent":["\"use client\";\n\nimport { useCallback, useMemo } from \"react\";\nimport { browserApiRequest } from \"@elqnt/api-client/browser\";\nimport type { ApiClientOptions } from \"@elqnt/api-client/browser\";\nimport type { SendEmailRequest, SendEmailResponse } from \"../models\";\n\ninterface UseEmailOptions {\n  baseUrl: string;\n  orgId: string;\n}\n\nexport function useEmail(options: UseEmailOptions) {\n  const apiOptions = useMemo<ApiClientOptions>(\n    () => ({ baseUrl: options.baseUrl, orgId: options.orgId }),\n    [options.baseUrl, options.orgId]\n  );\n\n  const send = useCallback(\n    async (request: SendEmailRequest): Promise<SendEmailResponse | null> => {\n      try {\n        const response = await browserApiRequest<SendEmailResponse>(\n          \"/api/v1/email/send\",\n          {\n            method: \"POST\",\n            body: request,\n            ...apiOptions,\n          }\n        );\n        return response.data ?? null;\n      } catch {\n        console.warn(\"Failed to send email notification\");\n        return null;\n      }\n    },\n    [apiOptions]\n  );\n\n  return { send };\n}\n"],"mappings":";;;AAEA,SAAS,aAAa,eAAe;AACrC,SAAS,yBAAyB;AAS3B,SAAS,SAAS,SAA0B;AACjD,QAAM,aAAa;AAAA,IACjB,OAAO,EAAE,SAAS,QAAQ,SAAS,OAAO,QAAQ,MAAM;AAAA,IACxD,CAAC,QAAQ,SAAS,QAAQ,KAAK;AAAA,EACjC;AAEA,QAAM,OAAO;AAAA,IACX,OAAO,YAAiE;AACtE,UAAI;AACF,cAAM,WAAW,MAAM;AAAA,UACrB;AAAA,UACA;AAAA,YACE,QAAQ;AAAA,YACR,MAAM;AAAA,YACN,GAAG;AAAA,UACL;AAAA,QACF;AACA,eAAO,SAAS,QAAQ;AAAA,MAC1B,QAAQ;AACN,gBAAQ,KAAK,mCAAmC;AAChD,eAAO;AAAA,MACT;AAAA,IACF;AAAA,IACA,CAAC,UAAU;AAAA,EACb;AAEA,SAAO,EAAE,KAAK;AAChB;","names":[]}