@linked.cm/zoho-cpaas 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 Linked contributors
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,40 @@
-# Temporary Holding Version
+# @linked.cm/zoho-cpaas
 
-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.
+An email provider for LINKED apps: it sends `LinkedEmail` messages (`@_linked/server-utils`), such
+as `@_linked/auth`'s sign-in codes and verification links, through
+[Zoho CPaaS](https://www.zoho.com/zeptomail/) (called ZeptoMail until September 2026). The API
+is unchanged: `POST https://api.zeptomail.com/v1.1/email` with `Authorization: Zoho-enczapikey …`.
+
+## Use
+
+```bash
+npm install @linked.cm/zoho-cpaas
+```
+
+The package's `./backend` is a `BackendProvider`. At boot it registers the provider with
+`LinkedEmail` **only when `ZEPTOMAIL_API_KEY` is set**. Without the key nothing is registered:
+in development `@_linked/auth` then prints what it would have emailed to the server log.
+
+| Variable | Required | Meaning |
+|---|---|---|
+| `ZEPTOMAIL_API_KEY` | to send | The Mail Agent's send token, with or without its `Zoho-enczapikey ` prefix. |
+| `ZEPTOMAIL_API_URL` | no | The send endpoint of your region. Default `https://api.zeptomail.com/v1.1/email` (US); `https` only, `http` only on localhost. |
+| `EMAIL_FROM` | no | The sender address, on a domain verified in the Mail Agent. Default `noreply@` the host of `SITE_ROOT`. |
+| `EMAIL_FROM_NAME` | no | The sender's display name. Default none. |
+
+A message's own `from` and `bounce_address` (in `EmailOptions`) win over these. Each email gets a
+plain text part made from its HTML; click and open tracking stay off, so links are not
+rewritten. A setting that cannot work stops the boot with a message naming the variable.
+
+A failed send rejects with the HTTP status and the API's error codes only, for example
+`Zoho CPaaS refused the email: 401 (TM_3201, SERR_157)`: never the key, the address, the subject
+or the body.
+
+Without the framework, the root entry exposes the pieces: `emailProviderFromEnv(env)`,
+`zohoCpaasProvider({transport})`, `zohoCpaasTransport({settings, fetch?})`, `settingsFromEnv(env)`,
+`htmlToText(html)`.
+
+## Develop
+
+`npm install && npm run build && npm test && npm run typecheck`. The tests load the built `lib/`
+with a mocked `fetch`; nothing is sent.

package/lib/esm/backend.d.ts

@@ -0,0 +1,14 @@
+import { BackendProvider } from '@_linked/server-utils/utils/BackendProvider';
+import './package.js';
+/**
+ * Registers Zoho CPaaS as `LinkedEmail`'s provider when `ZEPTOMAIL_API_KEY` is set. Without it
+ * nothing is registered, so in development `@_linked/auth` prints what it would have emailed.
+ * A setting that cannot work stops the boot with a message naming the variable.
+ */
+export default class ZohoCpaasBackendProvider extends BackendProvider {
+    setupBeforeControllers(): void;
+}
+/** What `setupBeforeControllers` does, for an environment; returns whether it registered. */
+export declare function registerFromEnv(env: Record<string, string | undefined>, options?: {
+    fetch?: typeof globalThis.fetch;
+}): boolean;

package/lib/esm/backend.js

@@ -0,0 +1,26 @@
+import { BackendProvider } from '@_linked/server-utils/utils/BackendProvider';
+import { LinkedEmail } from '@_linked/server-utils/utils/LinkedEmail';
+import { zohoCpaasProvider } from './provider.js';
+import './package.js';
+import { settingsFromEnv, zohoCpaasTransport } from './transport.js';
+/**
+ * Registers Zoho CPaaS as `LinkedEmail`'s provider when `ZEPTOMAIL_API_KEY` is set. Without it
+ * nothing is registered, so in development `@_linked/auth` prints what it would have emailed.
+ * A setting that cannot work stops the boot with a message naming the variable.
+ */
+export default class ZohoCpaasBackendProvider extends BackendProvider {
+    setupBeforeControllers() {
+        registerFromEnv(process.env);
+    }
+}
+/** What `setupBeforeControllers` does, for an environment; returns whether it registered. */
+export function registerFromEnv(env, options = {}) {
+    const settings = settingsFromEnv(env);
+    if (!settings)
+        return false;
+    const transport = zohoCpaasTransport({ settings, ...(options.fetch ? { fetch: options.fetch } : {}) });
+    LinkedEmail.setDefaultProvider(zohoCpaasProvider({ transport }));
+    console.log(`[zoho-cpaas] email is sent through Zoho CPaaS from ${settings.from.address}`);
+    return true;
+}
+//# sourceMappingURL=backend.js.map

package/lib/esm/backend.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,6CAA6C,CAAC;AAC9E,OAAO,EAAE,WAAW,EAAE,MAAM,yCAAyC,CAAC;AACtE,OAAO,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC;AAClD,OAAO,cAAc,CAAC;AACtB,OAAO,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAErE;;;;GAIG;AACH,MAAM,CAAC,OAAO,OAAO,wBAAyB,SAAQ,eAAe;IACnE,sBAAsB;QACpB,eAAe,CAAC,OAAO,CAAC,GAAG,CAAC,CAAC;IAC/B,CAAC;CACF;AAED,6FAA6F;AAC7F,MAAM,UAAU,eAAe,CAC7B,GAAuC,EACvC,UAA+C,EAAE;IAEjD,MAAM,QAAQ,GAAG,eAAe,CAAC,GAAG,CAAC,CAAC;IACtC,IAAI,CAAC,QAAQ;QAAE,OAAO,KAAK,CAAC;IAC5B,MAAM,SAAS,GAAG,kBAAkB,CAAC,EAAE,QAAQ,EAAE,GAAG,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;IACvG,WAAW,CAAC,kBAAkB,CAAC,iBAAiB,CAAC,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC;IACjE,OAAO,CAAC,GAAG,CAAC,sDAAsD,QAAQ,CAAC,IAAI,CAAC,OAAO,EAAE,CAAC,CAAC;IAC3F,OAAO,IAAI,CAAC;AACd,CAAC"}

package/lib/esm/index.d.ts

@@ -0,0 +1,3 @@
+import './package.js';
+export { DEFAULT_API_URL, KEY_PREFIX, SEND_TIMEOUT_MS, requestBody, settingsFromEnv, zohoCpaasTransport, type EmailTransport, type InlineImage, type OutgoingEmail, type Sender, type ZohoCpaasSettings, } from './transport.js';
+export { emailProviderFromEnv, htmlToText, toOutgoingEmail, zohoCpaasProvider } from './provider.js';

package/lib/esm/index.js

@@ -0,0 +1,7 @@
+// Registers the package with @_linked/core whichever entry a consumer imports.
+import './package.js';
+// The root entry: the transport, the settings and the provider, with no server dependency.
+// `./backend` is the BackendProvider an app loads to register the provider with LinkedEmail.
+export { DEFAULT_API_URL, KEY_PREFIX, SEND_TIMEOUT_MS, requestBody, settingsFromEnv, zohoCpaasTransport, } from './transport.js';
+export { emailProviderFromEnv, htmlToText, toOutgoingEmail, zohoCpaasProvider } from './provider.js';
+//# sourceMappingURL=index.js.map

package/lib/esm/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,+EAA+E;AAC/E,OAAO,cAAc,CAAC;AACtB,2FAA2F;AAC3F,6FAA6F;AAC7F,OAAO,EACL,eAAe,EACf,UAAU,EACV,eAAe,EACf,WAAW,EACX,eAAe,EACf,kBAAkB,GAMnB,MAAM,gBAAgB,CAAC;AACxB,OAAO,EAAE,oBAAoB,EAAE,UAAU,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,eAAe,CAAC"}

package/lib/esm/package.d.ts

@@ -0,0 +1,5 @@
+/** This package's own linked identity. */
+export declare const linkedShape: {
+    <T extends typeof import("@_linked/core/shapes/Shape.js").Shape>(constructor: T): void;
+    <T extends typeof import("@_linked/core/shapes/Shape.js").Shape>(config?: import("@_linked/core/utils/Package").ShapeConfig): (constructor: T) => void;
+}, linkedUtil: (constructor: any) => any, linkedOntology: (allFileExports: any, nameSpace: (term: string) => import("@_linked/core/utils/NodeReference.js").NodeReferenceValue, suggestedPrefixAndFileName: string, loadDataFunction?: () => Promise<unknown>, dataSource?: string | string[]) => void, registerPackageExport: (exportedObject: any) => void, registerPackageModule: (_module: any) => void, getPackageShape: (name: string) => import("@_linked/core/shapes/Shape.js").ShapeConstructor | undefined, packageExports: any, packageName: string;

package/lib/esm/package.js

@@ -0,0 +1,4 @@
+import { linkedPackage } from '@_linked/core/utils/Package';
+/** This package's own linked identity. */
+export const { linkedShape, linkedUtil, linkedOntology, registerPackageExport, registerPackageModule, getPackageShape, packageExports, packageName, } = linkedPackage('@linked.cm/zoho-cpaas');
+//# sourceMappingURL=package.js.map

package/lib/esm/package.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"package.js","sourceRoot":"","sources":["../../src/package.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,6BAA6B,CAAC;AAE5D,0CAA0C;AAC1C,MAAM,CAAC,MAAM,EACX,WAAW,EACX,UAAU,EACV,cAAc,EACd,qBAAqB,EACrB,qBAAqB,EACrB,eAAe,EACf,cAAc,EACd,WAAW,GACZ,GAAG,aAAa,CAAC,uBAAuB,CAAC,CAAC"}

package/lib/esm/provider.d.ts

@@ -0,0 +1,22 @@
+/**
+ * The `LinkedEmail` provider: takes the message the app (or `@_linked/auth`) built, adds a plain
+ * text part made from its HTML, and sends it through Zoho CPaaS.
+ *
+ * Only type imports from the framework, so it loads without a server.
+ */
+import type { EmailOptions, IEmailProvider } from '@_linked/server-utils/utils/LinkedEmail';
+import { type EmailTransport, type Env, type OutgoingEmail } from './transport.js';
+/** A plain text version of an HTML email: links kept as their URLs, tags dropped. */
+export declare function htmlToText(html: string): string;
+/** `LinkedEmail`'s options as one outgoing message, with a text part from the HTML. */
+export declare function toOutgoingEmail(options: EmailOptions): OutgoingEmail;
+export declare function zohoCpaasProvider({ transport }: {
+    transport: EmailTransport;
+}): IEmailProvider;
+/**
+ * The provider for this environment, or `undefined` without `ZEPTOMAIL_API_KEY`. Throws when a
+ * setting cannot work.
+ */
+export declare function emailProviderFromEnv(env: Env, { fetch }?: {
+    fetch?: typeof globalThis.fetch;
+}): IEmailProvider | undefined;

package/lib/esm/provider.js

@@ -0,0 +1,52 @@
+import { settingsFromEnv, zohoCpaasTransport } from './transport.js';
+/** A plain text version of an HTML email: links kept as their URLs, tags dropped. */
+export function htmlToText(html) {
+    const decode = (text) => text
+        .replace(/&lt;/g, '<')
+        .replace(/&gt;/g, '>')
+        .replace(/&quot;/g, '"')
+        .replace(/&#39;/g, "'")
+        .replace(/&nbsp;/g, ' ')
+        .replace(/&amp;/g, '&');
+    return decode(html
+        .replace(/<(style|head)[^>]*>[\s\S]*?<\/\1>/gi, '')
+        .replace(/<a\b[^>]*\bhref=(['"])(.*?)\1[^>]*>([\s\S]*?)<\/a>/gi, (_m, _q, href, label) => {
+        const text = label.replace(/<[^>]+>/g, '').trim();
+        return text && text !== href ? `${text}: ${href}` : href;
+    })
+        .replace(/<br\s*\/?>/gi, '\n')
+        .replace(/<\/(p|div|tr|h[1-6]|li|table)>/gi, '\n')
+        .replace(/<[^>]+>/g, ''))
+        .split('\n')
+        .map((line) => line.replace(/[ \t]+/g, ' ').trim())
+        .join('\n')
+        .replace(/\n{3,}/g, '\n\n')
+        .trim();
+}
+/** `LinkedEmail`'s options as one outgoing message, with a text part from the HTML. */
+export function toOutgoingEmail(options) {
+    return {
+        to: options.to.map(({ email_address }) => ({ address: email_address.address, name: email_address.name })),
+        subject: options.subject,
+        html: options.htmlbody,
+        text: htmlToText(options.htmlbody),
+        ...(options.from ? { from: { address: options.from.address, name: options.from.name } } : {}),
+        ...(options.bounce_address ? { bounceAddress: options.bounce_address } : {}),
+    };
+}
+export function zohoCpaasProvider({ transport }) {
+    return {
+        send: (options) => transport.send(toOutgoingEmail(options)),
+    };
+}
+/**
+ * The provider for this environment, or `undefined` without `ZEPTOMAIL_API_KEY`. Throws when a
+ * setting cannot work.
+ */
+export function emailProviderFromEnv(env, { fetch } = {}) {
+    const settings = settingsFromEnv(env);
+    if (!settings)
+        return undefined;
+    return zohoCpaasProvider({ transport: zohoCpaasTransport({ settings, ...(fetch ? { fetch } : {}) }) });
+}
+//# sourceMappingURL=provider.js.map

package/lib/esm/provider.js.map

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

package/lib/esm/transport.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Zoho CPaaS email (formerly ZeptoMail): its settings from the environment and a transport that
+ * sends one message through its send API (`POST /v1.1/email`, JSON). The API kept ZeptoMail's
+ * host, auth scheme and variable names when the product was renamed.
+ *
+ * Pure Node (global `fetch`, injectable): no framework imports.
+ */
+/** The send endpoint in the US data centre; other regions have their own host. */
+export declare const DEFAULT_API_URL = "https://api.zeptomail.com/v1.1/email";
+/** How a Mail Agent's send token is presented. */
+export declare const KEY_PREFIX = "Zoho-enczapikey ";
+/** How long one send may take before it counts as failed. */
+export declare const SEND_TIMEOUT_MS = 10000;
+export interface Sender {
+    address: string;
+    name?: string;
+}
+export interface ZohoCpaasSettings {
+    /** The send token, without its `Zoho-enczapikey ` prefix. */
+    apiKey: string;
+    apiUrl: string;
+    from: Sender;
+}
+/** An image the HTML shows as `cid:{cid}`. */
+export interface InlineImage {
+    cid: string;
+    mimeType: string;
+    content: Buffer;
+}
+/** One message as this package sends it. */
+export interface OutgoingEmail {
+    to: {
+        address: string;
+        name?: string;
+    }[];
+    subject: string;
+    html: string;
+    text: string;
+    /** Overrides the sender from the settings. */
+    from?: Sender;
+    bounceAddress?: string;
+    inlineImages?: InlineImage[];
+}
+export interface EmailTransport {
+    send(email: OutgoingEmail): Promise<void>;
+}
+export type Env = Record<string, string | undefined>;
+/**
+ * The settings, or `undefined` when `ZEPTOMAIL_API_KEY` is not set (no provider is registered).
+ * Throws, naming the variable, for a value that cannot work.
+ */
+export declare function settingsFromEnv(env: Env): ZohoCpaasSettings | undefined;
+/** The API's JSON for one message. Tracking stays off: it would rewrite sign-in links. */
+export declare function requestBody(email: OutgoingEmail, from: Sender): Record<string, unknown>;
+/**
+ * Send through Zoho CPaaS. A failure rejects with the HTTP status and the API's error codes
+ * only: never the key, the address, the subject or the body (which may carry links and codes).
+ */
+export declare function zohoCpaasTransport({ settings, fetch: fetchImpl, timeoutMs, }: {
+    settings: ZohoCpaasSettings;
+    fetch?: typeof fetch;
+    timeoutMs?: number;
+}): EmailTransport;

package/lib/esm/transport.js

@@ -0,0 +1,128 @@
+/**
+ * Zoho CPaaS email (formerly ZeptoMail): its settings from the environment and a transport that
+ * sends one message through its send API (`POST /v1.1/email`, JSON). The API kept ZeptoMail's
+ * host, auth scheme and variable names when the product was renamed.
+ *
+ * Pure Node (global `fetch`, injectable): no framework imports.
+ */
+/** The send endpoint in the US data centre; other regions have their own host. */
+export const DEFAULT_API_URL = 'https://api.zeptomail.com/v1.1/email';
+/** How a Mail Agent's send token is presented. */
+export const KEY_PREFIX = 'Zoho-enczapikey ';
+/** How long one send may take before it counts as failed. */
+export const SEND_TIMEOUT_MS = 10_000;
+const ADDRESS = /^[^\s@<>"]+@[^\s@<>"]+\.[^\s@<>"]+$/;
+/**
+ * The settings, or `undefined` when `ZEPTOMAIL_API_KEY` is not set (no provider is registered).
+ * Throws, naming the variable, for a value that cannot work.
+ */
+export function settingsFromEnv(env) {
+    let apiKey = (env.ZEPTOMAIL_API_KEY ?? '').trim();
+    if (!apiKey)
+        return undefined;
+    // the Mail Agent shows the token with its scheme; either form is accepted
+    apiKey = apiKey.replace(/^zoho-enczapikey(\s+|$)/i, '');
+    if (!apiKey || /\s/.test(apiKey))
+        throw new Error('ZEPTOMAIL_API_KEY is not a Zoho CPaaS send token');
+    const apiUrl = (env.ZEPTOMAIL_API_URL ?? '').trim() || DEFAULT_API_URL;
+    let url;
+    try {
+        url = new URL(apiUrl);
+    }
+    catch {
+        throw new Error(`ZEPTOMAIL_API_URL is not a URL: ${apiUrl}`);
+    }
+    const local = url.hostname === 'localhost' || url.hostname === '127.0.0.1';
+    if (url.protocol !== 'https:' && !(url.protocol === 'http:' && local)) {
+        throw new Error(`ZEPTOMAIL_API_URL must be https (http only on localhost): ${apiUrl}`);
+    }
+    let address = (env.EMAIL_FROM ?? '').trim();
+    if (!address) {
+        let host = '';
+        try {
+            host = new URL(env.SITE_ROOT ?? '').hostname;
+        }
+        catch {
+            // reported below
+        }
+        address = host ? `noreply@${host}` : '';
+    }
+    if (!ADDRESS.test(address)) {
+        throw new Error(`EMAIL_FROM must be an address on a sender domain verified in Zoho CPaaS (got "${address}")`);
+    }
+    const name = (env.EMAIL_FROM_NAME ?? '').trim();
+    return { apiKey, apiUrl: url.toString(), from: name ? { address, name } : { address } };
+}
+/** The API's JSON for one message. Tracking stays off: it would rewrite sign-in links. */
+export function requestBody(email, from) {
+    const sender = email.from ?? from;
+    return {
+        from: sender.name ? { address: sender.address, name: sender.name } : { address: sender.address },
+        to: email.to.map(({ address, name }) => ({ email_address: { address, name: name || address } })),
+        subject: email.subject,
+        htmlbody: email.html,
+        textbody: email.text,
+        ...(email.bounceAddress ? { bounce_address: email.bounceAddress } : {}),
+        ...(email.inlineImages?.length
+            ? {
+                inline_images: email.inlineImages.map((image) => ({
+                    cid: image.cid,
+                    mime_type: image.mimeType,
+                    content: image.content.toString('base64'),
+                })),
+            }
+            : {}),
+        track_clicks: false,
+        track_opens: false,
+    };
+}
+/** The API's error codes from a failed answer (`{error: {code, details: [{code}]}}`). */
+async function errorCodes(response) {
+    try {
+        const body = (await response.json());
+        const codes = [body.error?.code, ...(body.error?.details ?? []).map((d) => d?.code)].filter((code) => typeof code === 'string' && /^[A-Za-z0-9_]{1,32}$/.test(code));
+        return codes.length ? ` (${codes.join(', ')})` : '';
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Send through Zoho CPaaS. A failure rejects with the HTTP status and the API's error codes
+ * only: never the key, the address, the subject or the body (which may carry links and codes).
+ */
+export function zohoCpaasTransport({ settings, fetch: fetchImpl = fetch, timeoutMs = SEND_TIMEOUT_MS, }) {
+    return {
+        async send(email) {
+            let response;
+            const controller = new AbortController();
+            const timer = setTimeout(() => controller.abort(new DOMException('timed out', 'TimeoutError')), timeoutMs);
+            try {
+                response = await fetchImpl(settings.apiUrl, {
+                    method: 'POST',
+                    headers: {
+                        accept: 'application/json',
+                        'content-type': 'application/json',
+                        authorization: `${KEY_PREFIX}${settings.apiKey}`,
+                    },
+                    body: JSON.stringify(requestBody(email, settings.from)),
+                    signal: controller.signal,
+                    redirect: 'error',
+                });
+            }
+            catch (err) {
+                const name = err?.name;
+                throw new Error(name === 'TimeoutError'
+                    ? `Zoho CPaaS did not answer in ${timeoutMs} ms`
+                    : `Zoho CPaaS could not be reached (${name ?? 'error'})`);
+            }
+            finally {
+                clearTimeout(timer);
+            }
+            if (!response.ok)
+                throw new Error(`Zoho CPaaS refused the email: ${response.status}${await errorCodes(response)}`);
+            await response.body?.cancel().catch(() => { });
+        },
+    };
+}
+//# sourceMappingURL=transport.js.map

package/lib/esm/transport.js.map

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

package/package.json

@@ -1,6 +1,75 @@
 {
   "name": "@linked.cm/zoho-cpaas",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Zoho CPaaS (formerly ZeptoMail) email provider for LINKED apps: registers with LinkedEmail when ZEPTOMAIL_API_KEY is set.",
+  "type": "module",
+  "linked": {
+    "kind": "library"
+  },
+  "main": "lib/esm/index.js",
+  "module": "lib/esm/index.js",
+  "types": "lib/esm/index.d.ts",
+  "license": "ISC",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/linked-cm/zoho-cpaas.git"
+  },
+  "homepage": "https://github.com/linked-cm/zoho-cpaas#readme",
+  "bugs": {
+    "url": "https://github.com/linked-cm/zoho-cpaas/issues"
+  },
+  "files": [
+    "lib",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "npm exec linked dev",
+    "build": "linked build",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "node --test test/*.test.mjs"
+  },
+  "exports": {
+    ".": {
+      "types": "./lib/esm/index.d.ts",
+      "import": "./lib/esm/index.js"
+    },
+    "./backend": {
+      "types": "./lib/esm/backend.d.ts",
+      "import": "./lib/esm/backend.js"
+    },
+    "./package": {
+      "types": "./lib/esm/package.d.ts",
+      "import": "./lib/esm/package.js"
+    }
+  },
+  "typesVersions": {
+    "*": {
+      "*": [
+        "lib/esm/*"
+      ]
+    }
+  },
+  "dependencies": {
+    "@_linked/core": "^2.45.0",
+    "@_linked/server-utils": "^1.17.0"
+  },
+  "devDependencies": {
+    "@_linked/cli": "^1.60.0",
+    "@changesets/changelog-github": "^1.0.0",
+    "@changesets/cli": "^3.0.0",
+    "@types/node": "^22.0.0",
+    "typescript": "^5.9.2"
+  },
+  "keywords": [
+    "linked",
+    "email",
+    "zoho",
+    "zeptomail",
+    "cpaas"
+  ],
+  "packageManager": "npm@12.2.0"
+}