@stealthmark/core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/NOTICE

@@ -0,0 +1,4 @@
+StealthMark SDK
+Copyright 2026 Gastón Chevarria / StealthMark.io
+
+This product includes software developed by Gastón Chevarria / StealthMark.io (https://stealthmark.io).

package/README.md

@@ -1,3 +1,128 @@
-# Temporary Holding Version
+# @stealthmark/core
 
-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.
+**Framework-agnostic engine for detecting self-identified AI agents, serving an agent manifest and metering agent traffic.**
+
+> Detects only agents that identify themselves. It does not detect stealth bots and is not a security control.
+
+Detect AI agents that identify themselves, serve a structured agent manifest, and meter that traffic. Plain TypeScript, no runtime dependencies. It does not detect agents that disguise themselves, and it is not a security control.
+
+The manifest is StealthMark's own format. It is not an A2A Agent Card, an MCP server manifest or an adopted standard.
+
+## Installation
+
+```bash
+npm install @stealthmark/core
+```
+
+Requires Node.js 20 or newer.
+
+## Quick Start
+
+```typescript
+import { createStealthMark } from '@stealthmark/core';
+
+const sm = createStealthMark({
+  siteName: 'My SaaS',
+  capabilities: [
+    { id: 'search', endpoint: '/api/search', method: 'GET', description: 'Search products' },
+    { id: 'create-order', endpoint: '/api/orders', method: 'POST', hitl: true },
+  ],
+});
+
+// In your request handler:
+const result = sm.detect(request.headers);
+
+if (result.isAgent) {
+  return new Response(sm.manifestJson, {
+    headers: { 'content-type': 'application/agent+json' },
+  });
+}
+```
+
+`hitl` is advisory metadata for agents. StealthMark does not block, approve or rate-limit anything; enforce approvals in your own handler. The same goes for `pricing`: it is published in the manifest and never enforced.
+
+## Agent Detection
+
+StealthMark detects agents that identify themselves, via three signals (priority order):
+
+1. **Accept header**: `application/agent+json`
+2. **StealthMark header**: `x-stealthmark-agent`
+3. **User-Agent patterns**: GPTBot, ClaudeBot, PerplexityBot, etc.
+
+```typescript
+import { detectAgent } from '@stealthmark/core';
+
+const result = detectAgent(request.headers);
+// { isAgent: true, agentId: 'GPTBot', method: 'user-agent' }
+```
+
+All three signals are self-declared. Any client can send them, and agents that look like browsers are not detected.
+
+## Usage Metering
+
+Usage is counted per **agent event**: one HTTP request that identifies itself as an AI agent (via `Accept: application/agent+json`, the `x-stealthmark-agent` header, or a known agent token in the `User-Agent`). Identification is self-declared, so a human or script can send these signals and be counted, and agents that look like browsers are not counted. Events are reported best-effort and can be dropped (see below). They are batched and sent to `POST /v1/usage/ingest` with your site API key.
+
+```typescript
+const sm = createStealthMark({
+  siteName: 'My App',
+  apiKey: process.env.STEALTHMARK_API_KEY,
+  // usageEndpoint: 'https://...',          // or STEALTHMARK_USAGE_ENDPOINT
+  // reportUsage: false,                    // opt out (defaults to true when a key is set)
+  siteId: process.env.STEALTHMARK_SITE_ID,  // optional, stored as site_id (UUID of a registered site)
+  onQuotaExceeded: ({ pausedUntil, retryAfterSeconds, dropped }) => {
+    // Optional: surface the pause (log, alert, status page). Never throws into the SDK.
+    logger.warn(`StealthMark quota reached, reporting paused until ${new Date(pausedUntil).toISOString()}`);
+  },
+});
+
+sm.recordAgentEvent({
+  event_type: 'agent_request', // 'agent_request' | 'agent_blocked' | 'agent_manifest'
+  agent_identifier: 'GPTBot',
+  metadata: { path: '/pricing', method: 'GET' },
+});
+
+sm.usage.stats(); // { queued, sent, dropped, failures, pausedUntil, quotaExceededUntil }
+await sm.usage.flush(); // e.g. before a serverless function or process exits
+```
+
+The `@stealthmark/next` and `@stealthmark/express` adapters call `recordAgentEvent` exactly once per agent request for you.
+
+**Site attribution.** The adapters add `metadata.host` to every metered event (the `Host` header, lowercased, no port). The console groups and filters by `metadata.host`, automatically and with no config. Set `trustForwardedHost: true` to read the first `X-Forwarded-Host` value instead; enable it only behind a proxy you control.
+
+`siteId` (or the `STEALTHMARK_SITE_ID` env var) is optional and only stored on the event as `site_id`. It must be the UUID of a site registered to the same organization, otherwise it is stored as null; a value that is not a UUID is ignored with one warning. `normalizeHost`, `resolveRequestHost` and `buildEventMetadata` are exported if you meter events yourself.
+
+Behavior:
+
+- Never throws, never blocks the request path, no dependencies (global `fetch`); timers are unref'd so the reporter never keeps a process alive.
+- Batches by `maxBatch` (default 100, max 500) or `flushIntervalMs` (default 1000).
+- Retries 5xx and network errors three times (250 ms, 1 s, 4 s), then drops the batch (`failures`, `dropped`).
+- On `429 quota_exceeded` it stops sending for `retry_after_seconds` (default 300) and drops events meanwhile (`stats().dropped`), exposing the resume time as `stats().pausedUntil` (`null` when not paused; `quotaExceededUntil` is the same value kept for compatibility). Pass `onQuotaExceeded` to be told when it happens: it receives `{ pausedUntil, retryAfterSeconds, dropped }` once per 429, and exceptions it throws are swallowed. Events are not buffered across the pause, so a customer who wants to alert on it should wire this callback. Your site keeps serving traffic; only reporting pauses.
+- Any other `429` is the API's per-key rate limiter (`rate_limit_exceeded`), not a quota problem: nothing is dropped, `pausedUntil` stays `null` and `onQuotaExceeded` is not called. The batch stays queued and sending resumes after the `Retry-After` header (or `retry_after` in the body; 60 seconds when neither is present, never more than 300). Events recorded during the wait are queued, up to 10,000, and `flush()` returns without sending until the wait is over.
+- On serverless or Edge runtimes, pending timers can be frozen after the response is sent. Call `await sm.usage.flush()` (or `event.waitUntil(sm.usage.flush())`) at the end of the request when you need delivery guarantees.
+
+You can also use the reporter standalone:
+
+```typescript
+import { createUsageReporter } from '@stealthmark/core';
+
+const usage = createUsageReporter({ apiKey: process.env.STEALTHMARK_API_KEY ?? '', maxBatch: 50 });
+usage.record({ event_type: 'agent_request' });
+```
+
+## Data sent to StealthMark Cloud
+
+Only when an API key is configured (`apiKey` option or `STEALTHMARK_API_KEY`). Without a key the SDK makes no network calls. Requests not identified as agents are never reported.
+
+- Usage events (`POST /v1/usage/ingest`, sent with `Authorization: Bearer $STEALTHMARK_API_KEY`): event type, agent identifier, request path, method, host and timestamp. When no better identifier exists, the agent identifier is the request's `User-Agent`. Set `reportUsage: false` to turn this off.
+
+The default host is https://stealthmark-api-cifepjj5ca-uc.a.run.app, the StealthMark hosted API. Override it with `usageEndpoint` or `STEALTHMARK_USAGE_ENDPOINT`.
+
+## Route discovery
+
+`discoverCapabilities()` lists Next.js App Router `route.ts` handlers under `app/api` or `src/app/api` as capabilities. It does not scan Express, Fastify or Pages Router routes; declare those in `capabilities`. It never sets `pricing`, and sets `hitl` only for paths matching the `hitlKeywords` you pass.
+
+`discoverCapabilities()` needs Node (`fs`). Do not call it from Edge or browser code.
+
+## License
+
+Apache 2.0, see [LICENSE](./LICENSE) and [NOTICE](./NOTICE).

package/dist/auto-discovery.d.ts

@@ -0,0 +1,22 @@
+import type { Capability } from './types.js';
+export interface RouteDiscoveryOptions {
+    /** Root directory to scan from (defaults to process.cwd()) */
+    rootDir?: string;
+    /** Directories to scan (defaults to `src/app/api` and `app/api` under `rootDir`) */
+    apiPaths?: string[];
+    /**
+     * Opt-in: routes whose path contains one of these keywords are published with `hitl: true`.
+     * Empty by default, so discovery never guesses which routes need human approval.
+     */
+    hitlKeywords?: string[];
+}
+/**
+ * Lists Next.js App Router route handlers (`route.ts`, `route.js`, `route.mts`, `route.mjs`) found under
+ * `app/api` or `src/app/api` as capabilities. A handler is listed once per HTTP method it exports.
+ * Routes whose exported methods cannot be determined are skipped.
+ *
+ * It does not scan Express, Fastify or Pages Router routes, and it assumes nothing about pricing or
+ * human approval. Needs Node (`fs`): do not call it from Edge or browser code.
+ */
+export declare function discoverCapabilities(options?: RouteDiscoveryOptions): Capability[];
+//# sourceMappingURL=auto-discovery.d.ts.map

package/dist/auto-discovery.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"auto-discovery.d.ts","sourceRoot":"","sources":["../src/auto-discovery.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,YAAY,CAAC;AAIzD,MAAM,WAAW,qBAAqB;IACpC,8DAA8D;IAC9D,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oFAAoF;IACpF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB;;;OAGG;IACH,YAAY,CAAC,EAAE,MAAM,EAAE,CAAC;CACzB;AA8BD;;;;;;;GAOG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,GAAE,qBAA0B,GAAG,UAAU,EAAE,CAkBtF"}

package/dist/auto-discovery.js

@@ -0,0 +1,93 @@
+// ═══════════════════════════════════════════════════════════════════
+// @stealthmark/core — Route Discovery (Node only)
+// Lists Next.js App Router route handlers as manifest capabilities
+// ═══════════════════════════════════════════════════════════════════
+import * as fs from 'fs';
+import * as path from 'path';
+const HTTP_METHODS = ['GET', 'POST', 'PUT', 'PATCH', 'DELETE'];
+const METHOD_FUNCTION_EXPORT = /\bexport\s+(?:async\s+)?function\s+(GET|POST|PUT|PATCH|DELETE)\b/g;
+const METHOD_CONST_EXPORT = /\bexport\s+(?:const|let|var)\s+(GET|POST|PUT|PATCH|DELETE)\b/g;
+const EXPORT_LIST = /\bexport\s*\{([^}]*)\}/g;
+function detectExportedMethods(source) {
+    const methods = new Set();
+    for (const pattern of [METHOD_FUNCTION_EXPORT, METHOD_CONST_EXPORT]) {
+        for (const match of source.matchAll(pattern)) {
+            methods.add(match[1]);
+        }
+    }
+    for (const list of source.matchAll(EXPORT_LIST)) {
+        for (const specifier of list[1].split(',')) {
+            const parts = specifier.trim().split(/\s+as\s+/);
+            const exportedName = parts[parts.length - 1]?.trim();
+            if (exportedName && HTTP_METHODS.includes(exportedName)) {
+                methods.add(exportedName);
+            }
+        }
+    }
+    return methods;
+}
+/**
+ * Lists Next.js App Router route handlers (`route.ts`, `route.js`, `route.mts`, `route.mjs`) found under
+ * `app/api` or `src/app/api` as capabilities. A handler is listed once per HTTP method it exports.
+ * Routes whose exported methods cannot be determined are skipped.
+ *
+ * It does not scan Express, Fastify or Pages Router routes, and it assumes nothing about pricing or
+ * human approval. Needs Node (`fs`): do not call it from Edge or browser code.
+ */
+export function discoverCapabilities(options = {}) {
+    const rootDir = options.rootDir || (typeof process !== 'undefined' && process.cwd ? process.cwd() : '.');
+    const hitlKeywords = (options.hitlKeywords ?? []).map((kw) => kw.toLowerCase());
+    const capabilities = [];
+    const candidateDirs = options.apiPaths || [
+        path.join(rootDir, 'src', 'app', 'api'),
+        path.join(rootDir, 'app', 'api'),
+    ];
+    for (const dir of candidateDirs) {
+        if (fs.existsSync(dir)) {
+            scanAppApiDirectory(dir, dir, capabilities, hitlKeywords);
+            break; // Only scan the first matching API root directory to prevent duplicate routes
+        }
+    }
+    return capabilities;
+}
+function scanAppApiDirectory(currentDir, apiRootDir, out, hitlKeywords) {
+    const entries = fs.readdirSync(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+        const fullPath = path.join(currentDir, entry.name);
+        if (entry.isDirectory()) {
+            scanAppApiDirectory(fullPath, apiRootDir, out, hitlKeywords);
+        }
+        else if (entry.isFile() &&
+            (entry.name === 'route.ts' ||
+                entry.name === 'route.js' ||
+                entry.name === 'route.mts' ||
+                entry.name === 'route.mjs')) {
+            // Derive endpoint path relative to api root
+            const relDir = path.relative(apiRootDir, currentDir);
+            const endpoint = '/api' + (relDir ? '/' + relDir.replace(/\\/g, '/') : '');
+            try {
+                const content = fs.readFileSync(fullPath, 'utf8');
+                const detectedMethods = detectExportedMethods(content);
+                for (const method of detectedMethods) {
+                    const slug = endpoint
+                        .replace(/^\/api\/?/, '')
+                        .replace(/\//g, '-')
+                        .replace(/\[([^\]]+)\]/g, '$1') || 'root';
+                    const id = `${slug}-${method.toLowerCase()}`;
+                    const isHitl = hitlKeywords.some((kw) => endpoint.toLowerCase().includes(kw));
+                    out.push({
+                        id,
+                        endpoint,
+                        method,
+                        description: `API endpoint for ${endpoint} (${method})`,
+                        ...(isHitl ? { hitl: true } : {}),
+                    });
+                }
+            }
+            catch {
+                // Silently skip unreadable files
+            }
+        }
+    }
+}
+//# sourceMappingURL=auto-discovery.js.map

package/dist/auto-discovery.js.map

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

package/dist/create.d.ts

@@ -0,0 +1,51 @@
+import type { StealthMarkConfig, AgentManifest, DetectionResult, UsageEvent, AgentPolicy } from './types.js';
+import { type UsageReporter } from './usage-reporter.js';
+/** The StealthMark runtime instance returned by createStealthMark() */
+export interface StealthMarkInstance {
+    /** The generated agent manifest */
+    readonly manifest: AgentManifest;
+    /** Serialized manifest JSON string */
+    readonly manifestJson: string;
+    /** Detect whether a request is from an agent */
+    detect: (headers: Headers | Record<string, string | undefined>) => DetectionResult;
+    /** Standard response headers to add */
+    readonly responseHeaders: Record<string, string>;
+    /** Best-effort usage reporter (inert when no API key is configured) */
+    readonly usage: UsageReporter;
+    /** Effective handling of agent requests on ordinary paths */
+    readonly agentPolicy: AgentPolicy;
+    /** Registered site id attached to every metered event (config `siteId`, else STEALTHMARK_SITE_ID); undefined when not set or not a UUID */
+    readonly siteId: string | undefined;
+    /** Whether the adapters read the request host from X-Forwarded-Host instead of Host (config `trustForwardedHost`, default false) */
+    readonly trustForwardedHost: boolean;
+    /** Meter one agent event. Call exactly once per request identified as an AI agent. */
+    recordAgentEvent: (event: UsageEvent) => void;
+}
+/**
+ * Creates a configured StealthMark instance.
+ *
+ * This is the main entry point for the SDK. It initializes agent detection,
+ * manifest generation and usage metering.
+ *
+ * @example
+ * ```typescript
+ * import { createStealthMark } from '@stealthmark/core';
+ *
+ * const sm = createStealthMark({
+ *   siteName: 'My SaaS',
+ *   capabilities: [
+ *     { id: 'search', endpoint: '/api/search', method: 'GET' },
+ *   ],
+ * });
+ *
+ * // In your request handler:
+ * const result = sm.detect(request.headers);
+ * if (result.isAgent) {
+ *   return new Response(sm.manifestJson, {
+ *     headers: { 'content-type': 'application/agent+json' },
+ *   });
+ * }
+ * ```
+ */
+export declare function createStealthMark(config: StealthMarkConfig): StealthMarkInstance;
+//# sourceMappingURL=create.d.ts.map

package/dist/create.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.d.ts","sourceRoot":"","sources":["../src/create.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EACV,iBAAiB,EACjB,aAAa,EACb,eAAe,EACf,UAAU,EACV,WAAW,EACZ,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAuB,KAAK,aAAa,EAAE,MAAM,qBAAqB,CAAC;AAE9E,uEAAuE;AACvE,MAAM,WAAW,mBAAmB;IAClC,mCAAmC;IACnC,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,sCAAsC;IACtC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,gDAAgD;IAChD,MAAM,EAAE,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,KAAK,eAAe,CAAC;IACnF,uCAAuC;IACvC,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjD,uEAAuE;IACvE,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,6DAA6D;IAC7D,QAAQ,CAAC,WAAW,EAAE,WAAW,CAAC;IAClC,2IAA2I;IAC3I,QAAQ,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC;IACpC,oIAAoI;IACpI,QAAQ,CAAC,kBAAkB,EAAE,OAAO,CAAC;IACrC,sFAAsF;IACtF,gBAAgB,EAAE,CAAC,KAAK,EAAE,UAAU,KAAK,IAAI,CAAC;CAC/C;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,iBAAiB,GAAG,mBAAmB,CAqChF"}

package/dist/create.js

@@ -0,0 +1,94 @@
+// ═══════════════════════════════════════════════════════════════════
+// @stealthmark/core — Factory & Orchestrator
+// Creates a configured StealthMark instance that handles requests
+// ═══════════════════════════════════════════════════════════════════
+import { detectAgent } from './detect-agent.js';
+import { generateManifest, serializeManifest } from './manifest.js';
+import { createUsageReporter } from './usage-reporter.js';
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+function readEnv(name) {
+    if (typeof process === 'undefined' || !process.env)
+        return undefined;
+    switch (name) {
+        case 'STEALTHMARK_API_KEY':
+            return process.env.STEALTHMARK_API_KEY || undefined;
+        case 'STEALTHMARK_USAGE_ENDPOINT':
+            return process.env.STEALTHMARK_USAGE_ENDPOINT || undefined;
+        case 'STEALTHMARK_SITE_ID':
+            return process.env.STEALTHMARK_SITE_ID || undefined;
+    }
+}
+/**
+ * The ingest API rejects the whole batch when one event carries a site_id that is not a UUID, so a
+ * malformed id is dropped (with one warning) instead of costing the site its metered events.
+ */
+function resolveSiteId(configured) {
+    const raw = configured?.trim() || readEnv('STEALTHMARK_SITE_ID')?.trim();
+    if (!raw)
+        return undefined;
+    if (UUID_PATTERN.test(raw))
+        return raw.toLowerCase();
+    if (typeof console !== 'undefined') {
+        console.warn('[stealthmark] siteId ignored: expected the UUID of a site registered in the StealthMark console.');
+    }
+    return undefined;
+}
+/**
+ * Creates a configured StealthMark instance.
+ *
+ * This is the main entry point for the SDK. It initializes agent detection,
+ * manifest generation and usage metering.
+ *
+ * @example
+ * ```typescript
+ * import { createStealthMark } from '@stealthmark/core';
+ *
+ * const sm = createStealthMark({
+ *   siteName: 'My SaaS',
+ *   capabilities: [
+ *     { id: 'search', endpoint: '/api/search', method: 'GET' },
+ *   ],
+ * });
+ *
+ * // In your request handler:
+ * const result = sm.detect(request.headers);
+ * if (result.isAgent) {
+ *   return new Response(sm.manifestJson, {
+ *     headers: { 'content-type': 'application/agent+json' },
+ *   });
+ * }
+ * ```
+ */
+export function createStealthMark(config) {
+    const manifest = generateManifest(config);
+    const manifestJson = serializeManifest(manifest);
+    const usageApiKey = config.apiKey ?? readEnv('STEALTHMARK_API_KEY');
+    const siteId = resolveSiteId(config.siteId);
+    const trustForwardedHost = config.trustForwardedHost === true;
+    const usage = createUsageReporter({
+        apiKey: config.reportUsage === false ? '' : (usageApiKey ?? ''),
+        endpoint: config.usageEndpoint ?? readEnv('STEALTHMARK_USAGE_ENDPOINT'),
+        onQuotaExceeded: config.onQuotaExceeded,
+    });
+    const responseHeaders = {
+        'x-stealthmark-shield': 'ACTIVE',
+        'x-stealthmark-agent-policy': config.agentPolicy ?? 'observe',
+        ...(config.headers ?? {}),
+    };
+    return {
+        manifest,
+        manifestJson,
+        agentPolicy: config.agentPolicy ?? 'observe',
+        siteId,
+        trustForwardedHost,
+        detect(headers) {
+            return detectAgent(headers, config.agentPatterns);
+        },
+        responseHeaders,
+        usage,
+        recordAgentEvent(event) {
+            usage.record(siteId && !event.site_id ? { ...event, site_id: siteId } : event);
+        },
+    };
+}
+//# sourceMappingURL=create.js.map

package/dist/create.js.map

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

package/dist/detect-agent.d.ts

@@ -0,0 +1,18 @@
+import type { DetectionResult } from './types.js';
+/**
+ * Detects whether an incoming HTTP request originates from an autonomous AI agent.
+ *
+ * Detection is performed via three explicit signals (checked in priority order):
+ * 1. **Accept header**: `application/agent+json`
+ * 2. **StealthMark header**: `x-stealthmark-agent` presence
+ * 3. **User-Agent pattern matching**: vendor crawler tokens plus self-declared agent identifiers.
+ *    Google-Extended is deliberately absent: it is a robots.txt token, never sent as a User-Agent.
+ *
+ * Plain `application/json` requests are never classified as agents, so a site's own API calls are not metered.
+ *
+ * @param headers - Standard Headers object or plain Record
+ * @param extraPatterns - Additional User-Agent substrings to detect
+ * @returns DetectionResult with isAgent flag and detection metadata
+ */
+export declare function detectAgent(headers: Headers | Record<string, string | undefined>, extraPatterns?: string[]): DetectionResult;
+//# sourceMappingURL=detect-agent.d.ts.map

package/dist/detect-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"detect-agent.d.ts","sourceRoot":"","sources":["../src/detect-agent.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAgDlD;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,WAAW,CACzB,OAAO,EAAE,OAAO,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,EACrD,aAAa,GAAE,MAAM,EAAO,GAC3B,eAAe,CAoDjB"}