@usenotra/agentside 0.0.0-stage → 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -1,3 +1,5 @@
1
- # Temporary Holding Version
1
+ # agentside
2
2
 
3
- 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.
3
+ Serve markdown versions of your pages to AI agents and A/B test what they read. Built on Effect. By [Notra](https://usenotra.com).
4
+
5
+ Docs: [agentside.usenotra.com/docs](https://agentside.usenotra.com/docs). Usage and benchmarks: [GitHub](https://github.com/usenotra/agentside#readme).
@@ -0,0 +1,3 @@
1
+ import type { Agent } from "./types.js";
2
+ export declare function detectAgent(userAgent: string | null | undefined): Agent | null;
3
+ export declare const KNOWN_AGENTS: readonly Agent[];
package/dist/agents.js ADDED
@@ -0,0 +1,36 @@
1
+ const AGENTS = [
2
+ ["chatgpt-user", "ChatGPT-User", "OpenAI", "user-action"],
3
+ ["oai-searchbot", "OAI-SearchBot", "OpenAI", "search"],
4
+ ["gptbot", "GPTBot", "OpenAI", "training"],
5
+ ["claude-user", "Claude-User", "Anthropic", "user-action"],
6
+ ["claude-searchbot", "Claude-SearchBot", "Anthropic", "search"],
7
+ ["claudebot", "ClaudeBot", "Anthropic", "training"],
8
+ ["claude-web", "Claude-Web", "Anthropic", "user-action"],
9
+ ["anthropic-ai", "Anthropic-ai", "Anthropic", "training"],
10
+ ["perplexity-user", "Perplexity-User", "Perplexity", "user-action"],
11
+ ["perplexitybot", "PerplexityBot", "Perplexity", "search"],
12
+ ["mistralai-user", "MistralAI-User", "Mistral", "user-action"],
13
+ ["google-extended", "Google-Extended", "Google", "training"],
14
+ ["googleother", "GoogleOther", "Google", "training"],
15
+ ["applebot-extended", "Applebot-Extended", "Apple", "training"],
16
+ ["meta-externalagent", "Meta-ExternalAgent", "Meta", "training"],
17
+ ["meta-externalfetcher", "Meta-ExternalFetcher", "Meta", "user-action"],
18
+ ["duckassistbot", "DuckAssistBot", "DuckDuckGo", "search"],
19
+ ["youbot", "YouBot", "You.com", "search"],
20
+ ["cohere-ai", "cohere-ai", "Cohere", "training"],
21
+ ["amazonbot", "Amazonbot", "Amazon", "training"],
22
+ ["bytespider", "Bytespider", "ByteDance", "training"],
23
+ ["ccbot", "CCBot", "Common Crawl", "training"],
24
+ ["diffbot", "Diffbot", "Diffbot", "training"],
25
+ ["imagesiftbot", "ImagesiftBot", "ImageSift", "training"],
26
+ ["omgilibot", "Omgilibot", "Webz.io", "training"],
27
+ ];
28
+ const BY_TOKEN = new Map(AGENTS.map(([token, name, vendor, purpose]) => [token, { name, vendor, purpose }]));
29
+ const PATTERN = new RegExp(AGENTS.map(([token]) => token.replace(/[.*+?^${}()|[\]\\-]/g, "\\$&")).join("|"), "i");
30
+ export function detectAgent(userAgent) {
31
+ if (!userAgent)
32
+ return null;
33
+ const match = PATTERN.exec(userAgent);
34
+ return match ? (BY_TOKEN.get(match[0].toLowerCase()) ?? null) : null;
35
+ }
36
+ export const KNOWN_AGENTS = [...BY_TOKEN.values()];
@@ -0,0 +1,11 @@
1
+ import type { AgentsideConfig } from "./types.js";
2
+ export interface PrerenderOptions {
3
+ readonly outDir: string;
4
+ readonly paths?: readonly string[];
5
+ readonly siteUrl?: string;
6
+ }
7
+ export interface PrerenderResult {
8
+ readonly written: readonly string[];
9
+ readonly skipped: readonly string[];
10
+ }
11
+ export declare function prerender(config: AgentsideConfig, options: PrerenderOptions): Promise<PrerenderResult>;
package/dist/build.js ADDED
@@ -0,0 +1,32 @@
1
+ import { mkdir, writeFile } from "node:fs/promises";
2
+ import { dirname, join } from "node:path";
3
+ import { Effect, Exit } from "effect";
4
+ import { make } from "./core.js";
5
+ import { toMarkdownPath } from "./text.js";
6
+ export async function prerender(config, options) {
7
+ const server = Effect.runSync(make({ ...config, cache: false }));
8
+ const paths = options.paths ?? Object.keys(config.routes).filter((pattern) => !pattern.includes("["));
9
+ const siteUrl = options.siteUrl ?? "http://localhost";
10
+ const written = [];
11
+ const skipped = [];
12
+ const failures = [];
13
+ await Promise.all(paths.map(async (path) => {
14
+ const exit = await Effect.runPromiseExit(server.serve(path, new Request(`${siteUrl}${path}`), null));
15
+ if (Exit.isFailure(exit)) {
16
+ const error = exit.cause.reasons.find((reason) => reason._tag === "Fail")?.error;
17
+ if (error?._tag === "NotFound")
18
+ skipped.push(path);
19
+ else
20
+ failures.push(`${path}: ${error?._tag ?? "Defect"}`);
21
+ return;
22
+ }
23
+ const file = join(options.outDir, toMarkdownPath(path));
24
+ await mkdir(dirname(file), { recursive: true });
25
+ await writeFile(file, exit.value.body);
26
+ written.push(file);
27
+ }));
28
+ if (failures.length > 0) {
29
+ throw new Error(`agentside: ${failures.length} twin(s) failed to prerender\n${failures.join("\n")}`);
30
+ }
31
+ return { written, skipped };
32
+ }
package/dist/core.d.ts ADDED
@@ -0,0 +1,20 @@
1
+ import { Effect } from "effect";
2
+ import { type ServeError } from "./errors.js";
3
+ import type { Agent, AgentsideConfig, Source } from "./types.js";
4
+ export declare const CONTROL = "control";
5
+ export interface Match {
6
+ readonly pattern: string;
7
+ readonly params: Record<string, string>;
8
+ readonly source: Source;
9
+ }
10
+ export interface Served {
11
+ readonly body: string;
12
+ readonly tokens: number;
13
+ readonly variant: string;
14
+ readonly cached: boolean;
15
+ }
16
+ export declare const make: (config: AgentsideConfig) => Effect.Effect<{
17
+ match: (path: string) => Match | null;
18
+ serve: (path: string, request: Request, agent: Agent | null) => Effect.Effect<Served, ServeError, never>;
19
+ }, never, never>;
20
+ export declare function markdownResponse(body: string, config: AgentsideConfig, status?: number, extra?: Record<string, string>, tokens?: number): Response;
package/dist/core.js ADDED
@@ -0,0 +1,150 @@
1
+ import { Cache, Effect, Equal, Exit, Hash, Schedule } from "effect";
2
+ import { NotFound, RemoteFailed, RenderFailed, SourceTimeout } from "./errors.js";
3
+ import { estimateTokens, normalizeUnicode } from "./text.js";
4
+ export const CONTROL = "control";
5
+ class Key {
6
+ path;
7
+ variant;
8
+ source;
9
+ context;
10
+ constructor(path, variant, source, context) {
11
+ this.path = path;
12
+ this.variant = variant;
13
+ this.source = source;
14
+ this.context = context;
15
+ }
16
+ [Equal.symbol](that) {
17
+ return that instanceof Key && that.path === this.path && that.variant === this.variant;
18
+ }
19
+ [Hash.symbol]() {
20
+ return Hash.string(`${this.variant}\0${this.path}`);
21
+ }
22
+ }
23
+ function compileParamRoute(pattern, source) {
24
+ const keys = [];
25
+ const body = pattern
26
+ .split("/")
27
+ .map((segment) => {
28
+ const param = /^\[(\.\.\.)?([^\]]+)\]$/.exec(segment);
29
+ if (!param)
30
+ return segment.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
31
+ keys.push(param[2] ?? "");
32
+ return param[1] ? "(.+)" : "([^/]+)";
33
+ })
34
+ .join("/");
35
+ return { pattern, regex: new RegExp(`^${body}$`), keys, source };
36
+ }
37
+ function matchesAgent(variant, agent) {
38
+ if (!agent)
39
+ return false;
40
+ return ((variant.agents?.some((name) => name.toLowerCase() === agent.name.toLowerCase()) ?? false) ||
41
+ (variant.vendors?.some((vendor) => vendor.toLowerCase() === agent.vendor.toLowerCase()) ?? false) ||
42
+ (variant.purposes?.includes(agent.purpose) ?? false));
43
+ }
44
+ const loadSource = (source, context, timeoutMs, retries) => {
45
+ const { path } = context;
46
+ if (typeof source === "string")
47
+ return Effect.succeed(source);
48
+ const load = typeof source === "function"
49
+ ? Effect.tryPromise({
50
+ try: async () => source(context),
51
+ catch: (cause) => new RenderFailed({ path, cause }),
52
+ })
53
+ : Effect.gen(function* () {
54
+ const url = typeof source.url === "string" ? source.url : source.url(context);
55
+ const response = yield* Effect.tryPromise({
56
+ try: (signal) => fetch(url, { headers: { accept: "text/markdown, text/plain;q=0.9", ...source.headers }, signal }),
57
+ catch: (cause) => new RemoteFailed({ path, url, cause }),
58
+ });
59
+ if (response.status === 404)
60
+ return null;
61
+ if (!response.ok)
62
+ return yield* new RemoteFailed({ path, url, status: response.status });
63
+ return yield* Effect.tryPromise({
64
+ try: () => response.text(),
65
+ catch: (cause) => new RemoteFailed({ path, url, cause }),
66
+ });
67
+ }).pipe(Effect.retry({
68
+ times: retries,
69
+ schedule: Schedule.exponential("100 millis"),
70
+ while: (error) => error._tag === "RemoteFailed" && (error.status === undefined || error.status >= 500),
71
+ }));
72
+ return load.pipe(Effect.map((body) => body ?? null), Effect.timeoutOrElse({ duration: timeoutMs, orElse: () => Effect.fail(new SourceTimeout({ path, timeoutMs })) }));
73
+ };
74
+ export const make = Effect.fnUntraced(function* (config) {
75
+ const exact = new Map();
76
+ const params = [];
77
+ for (const [pattern, source] of Object.entries(config.routes)) {
78
+ if (!pattern.startsWith("/"))
79
+ throw new Error(`agentside: route "${pattern}" must start with "/"`);
80
+ if (pattern.includes("["))
81
+ params.push(compileParamRoute(pattern, source));
82
+ else
83
+ exact.set(pattern.length > 1 ? pattern.replace(/\/+$/, "") : pattern, source);
84
+ }
85
+ const timeoutMs = config.timeoutMs ?? 5000;
86
+ const retries = config.retries ?? 2;
87
+ const variants = config.variants ?? {};
88
+ const render = (key) => loadSource(key.source, key.context, timeoutMs, retries).pipe(Effect.flatMap((body) => (body === null ? Effect.fail(new NotFound({ path: key.path })) : Effect.succeed(body))), Effect.map((raw) => {
89
+ const body = config.normalize === false ? raw : normalizeUnicode(raw);
90
+ return { body, tokens: estimateTokens(body), renderedAt: performance.now() };
91
+ }));
92
+ const cache = config.cache === false
93
+ ? null
94
+ : yield* Cache.makeWith(render, {
95
+ capacity: config.cache?.capacity ?? 1000,
96
+ timeToLive: (exit) => (Exit.isSuccess(exit) ? (config.cache ? (config.cache.ttlMs ?? 300_000) : 300_000) : 0),
97
+ });
98
+ const load = (key) => {
99
+ const started = performance.now();
100
+ return Effect.map(cache ? Cache.get(cache, key) : render(key), ({ body, tokens, renderedAt }) => ({
101
+ body,
102
+ tokens,
103
+ cached: renderedAt < started,
104
+ }));
105
+ };
106
+ const match = (path) => {
107
+ const source = exact.get(path);
108
+ if (source !== undefined)
109
+ return { pattern: path, params: {}, source };
110
+ for (const route of params) {
111
+ const result = route.regex.exec(path);
112
+ if (!result)
113
+ continue;
114
+ const values = {};
115
+ route.keys.forEach((key, index) => {
116
+ values[key] = decodeURIComponent(result[index + 1] ?? "");
117
+ });
118
+ return { pattern: route.pattern, params: values, source: route.source };
119
+ }
120
+ return null;
121
+ };
122
+ const serve = (path, request, agent) => Effect.gen(function* () {
123
+ const found = match(path);
124
+ if (!found)
125
+ return yield* new NotFound({ path });
126
+ const context = { path, params: found.params, request, agent };
127
+ const variant = variants[found.pattern]?.find((candidate) => matchesAgent(candidate, agent));
128
+ const control = load(new Key(path, CONTROL, found.source, context)).pipe(Effect.map((result) => ({ ...result, variant: CONTROL })));
129
+ if (!variant)
130
+ return yield* control;
131
+ return yield* load(new Key(path, variant.id, variant.source, context)).pipe(Effect.map((result) => ({ ...result, variant: variant.id })), Effect.catch((error) => {
132
+ config.onError?.(error, path);
133
+ return control;
134
+ }));
135
+ });
136
+ return { match, serve };
137
+ });
138
+ export function markdownResponse(body, config, status = 200, extra, tokens = estimateTokens(body)) {
139
+ const headers = new Headers({
140
+ "Content-Type": "text/markdown; charset=utf-8",
141
+ "X-Content-Type-Options": "nosniff",
142
+ "X-Markdown-Tokens": String(tokens),
143
+ Vary: "Accept, User-Agent",
144
+ "Cache-Control": config.cacheControl ?? "public, max-age=3600",
145
+ ...extra,
146
+ });
147
+ if (config.noindex !== false)
148
+ headers.set("X-Robots-Tag", "noindex");
149
+ return new Response(body, { status, headers });
150
+ }
@@ -0,0 +1,2 @@
1
+ export { CONTROL, make, markdownResponse, type Match, type Served } from "./core.js";
2
+ export { NotFound, RemoteFailed, RenderFailed, SourceTimeout, type ServeError } from "./errors.js";
package/dist/effect.js ADDED
@@ -0,0 +1,2 @@
1
+ export { CONTROL, make, markdownResponse } from "./core.js";
2
+ export { NotFound, RemoteFailed, RenderFailed, SourceTimeout } from "./errors.js";
@@ -0,0 +1,28 @@
1
+ import { Schema } from "effect";
2
+ declare const NotFound_base: Schema.Class<NotFound, Schema.TaggedStruct<"NotFound", {
3
+ readonly path: Schema.String;
4
+ }>, import("effect/Cause").YieldableError>;
5
+ export declare class NotFound extends NotFound_base {
6
+ }
7
+ declare const RenderFailed_base: Schema.Class<RenderFailed, Schema.TaggedStruct<"RenderFailed", {
8
+ readonly path: Schema.String;
9
+ readonly cause: Schema.Defect;
10
+ }>, import("effect/Cause").YieldableError>;
11
+ export declare class RenderFailed extends RenderFailed_base {
12
+ }
13
+ declare const RemoteFailed_base: Schema.Class<RemoteFailed, Schema.TaggedStruct<"RemoteFailed", {
14
+ readonly path: Schema.String;
15
+ readonly url: Schema.String;
16
+ readonly status: Schema.optional<Schema.Number>;
17
+ readonly cause: Schema.optional<Schema.Defect>;
18
+ }>, import("effect/Cause").YieldableError>;
19
+ export declare class RemoteFailed extends RemoteFailed_base {
20
+ }
21
+ declare const SourceTimeout_base: Schema.Class<SourceTimeout, Schema.TaggedStruct<"SourceTimeout", {
22
+ readonly path: Schema.String;
23
+ readonly timeoutMs: Schema.Number;
24
+ }>, import("effect/Cause").YieldableError>;
25
+ export declare class SourceTimeout extends SourceTimeout_base {
26
+ }
27
+ export type ServeError = NotFound | RenderFailed | RemoteFailed | SourceTimeout;
28
+ export {};
package/dist/errors.js ADDED
@@ -0,0 +1,22 @@
1
+ import { Schema } from "effect";
2
+ export class NotFound extends Schema.TaggedError()("NotFound", {
3
+ path: Schema.String,
4
+ }) {
5
+ }
6
+ export class RenderFailed extends Schema.TaggedError()("RenderFailed", {
7
+ path: Schema.String,
8
+ cause: Schema.Defect(),
9
+ }) {
10
+ }
11
+ export class RemoteFailed extends Schema.TaggedError()("RemoteFailed", {
12
+ path: Schema.String,
13
+ url: Schema.String,
14
+ status: Schema.optional(Schema.Number),
15
+ cause: Schema.optional(Schema.Defect()),
16
+ }) {
17
+ }
18
+ export class SourceTimeout extends Schema.TaggedError()("SourceTimeout", {
19
+ path: Schema.String,
20
+ timeoutMs: Schema.Number,
21
+ }) {
22
+ }
@@ -0,0 +1,14 @@
1
+ import type { AgentsideConfig, RemoteSource, RenderContext } from "./types.js";
2
+ export { detectAgent, KNOWN_AGENTS } from "./agents.js";
3
+ export { NotFound, RemoteFailed, RenderFailed, SourceTimeout, type ServeError } from "./errors.js";
4
+ export { negotiateFormat } from "./negotiate.js";
5
+ export { estimateTokens, normalizeUnicode, toMarkdownPath } from "./text.js";
6
+ export type * from "./types.js";
7
+ export declare function remote(url: string | ((context: RenderContext) => string), options?: {
8
+ headers?: Record<string, string>;
9
+ }): RemoteSource;
10
+ export declare function agentside(config: AgentsideConfig): {
11
+ serve: (request: Request, pathname?: string) => Promise<Response>;
12
+ handle(request: Request, next: () => Promise<Response>): Promise<Response>;
13
+ };
14
+ export type Agentside = ReturnType<typeof agentside>;
package/dist/index.js ADDED
@@ -0,0 +1,90 @@
1
+ import { Effect, Exit } from "effect";
2
+ import { detectAgent } from "./agents.js";
3
+ import { make, markdownResponse } from "./core.js";
4
+ import { negotiateFormat } from "./negotiate.js";
5
+ import { toMarkdownPath, toPagePath } from "./text.js";
6
+ export { detectAgent, KNOWN_AGENTS } from "./agents.js";
7
+ export { NotFound, RemoteFailed, RenderFailed, SourceTimeout } from "./errors.js";
8
+ export { negotiateFormat } from "./negotiate.js";
9
+ export { estimateTokens, normalizeUnicode, toMarkdownPath } from "./text.js";
10
+ const SERVABLE_METHODS = new Set(["GET", "HEAD"]);
11
+ export function remote(url, options = {}) {
12
+ return options.headers ? { _tag: "remote", url, headers: options.headers } : { _tag: "remote", url };
13
+ }
14
+ function setHeaders(response, headers) {
15
+ try {
16
+ for (const [name, value] of Object.entries(headers)) {
17
+ const existing = response.headers.get(name);
18
+ if (name === "Vary" && existing) {
19
+ const tokens = existing.toLowerCase().split(",").map((token) => token.trim());
20
+ const missing = value.split(", ").filter((token) => !tokens.includes(token.toLowerCase()));
21
+ if (missing.length > 0)
22
+ response.headers.set(name, `${existing}, ${missing.join(", ")}`);
23
+ }
24
+ else {
25
+ response.headers.set(name, existing && name === "Link" ? `${existing}, ${value}` : value);
26
+ }
27
+ }
28
+ return response;
29
+ }
30
+ catch {
31
+ return setHeaders(new Response(response.body, response), headers);
32
+ }
33
+ }
34
+ export function agentside(config) {
35
+ const server = Effect.runSync(make(config));
36
+ const skip = config.skip ?? [];
37
+ const isSkipped = (pathname) => skip.some((prefix) => pathname === prefix || pathname.startsWith(prefix.endsWith("/") ? prefix : `${prefix}/`));
38
+ async function render(request, pathname, agent = detectAgent(request.headers.get("user-agent"))) {
39
+ const started = performance.now();
40
+ const path = toPagePath(pathname);
41
+ const exit = await Effect.runPromiseExit(server.serve(path, request, agent));
42
+ if (Exit.isSuccess(exit)) {
43
+ const { body, tokens, variant, cached } = exit.value;
44
+ config.onServe?.({ path, variant, agent, status: 200, cached, durationMs: performance.now() - started });
45
+ return markdownResponse(request.method === "HEAD" ? "" : body, config, 200, { "X-Agentside-Variant": variant }, tokens);
46
+ }
47
+ const error = exit.cause.reasons.find((reason) => reason._tag === "Fail")?.error;
48
+ if (error?._tag === "NotFound") {
49
+ return markdownResponse(`# Not found\n\nNo markdown version of ${path} exists.\n`, config, 404);
50
+ }
51
+ config.onError?.(error ?? exit.cause, path);
52
+ return markdownResponse("# Temporarily unavailable\n\nTry again shortly.\n", config, 503, { "Retry-After": "30" });
53
+ }
54
+ return {
55
+ serve: (request, pathname = new URL(request.url).pathname) => render(request, pathname),
56
+ async handle(request, next) {
57
+ if (!SERVABLE_METHODS.has(request.method))
58
+ return next();
59
+ const { pathname } = new URL(request.url);
60
+ if (isSkipped(pathname))
61
+ return next();
62
+ if (pathname.endsWith(".md")) {
63
+ return render(request, pathname);
64
+ }
65
+ const accept = request.headers.get("accept");
66
+ const format = negotiateFormat(accept);
67
+ const agent = detectAgent(request.headers.get("user-agent"));
68
+ if (format === "markdown" || agent) {
69
+ const response = await render(request, pathname, agent);
70
+ if (response.ok)
71
+ return response;
72
+ return setHeaders(await next(), { Vary: "Accept, User-Agent" });
73
+ }
74
+ if (format === null) {
75
+ return new Response("Not Acceptable\n\nSupported: text/html, text/markdown\n", {
76
+ status: 406,
77
+ headers: { "Content-Type": "text/plain; charset=utf-8", Vary: "Accept, User-Agent" },
78
+ });
79
+ }
80
+ const response = await next();
81
+ if (config.linkHeader === false || !server.match(toPagePath(pathname))) {
82
+ return setHeaders(response, { Vary: "Accept" });
83
+ }
84
+ return setHeaders(response, {
85
+ Link: `<${toMarkdownPath(pathname)}>; rel="alternate"; type="text/markdown"`,
86
+ Vary: "Accept",
87
+ });
88
+ },
89
+ };
90
+ }
@@ -0,0 +1,2 @@
1
+ import type { Format } from "./types.js";
2
+ export declare function negotiateFormat(accept: string | null | undefined): Format | null;
@@ -0,0 +1,40 @@
1
+ const HTML_TYPES = new Set(["text/html", "application/xhtml+xml"]);
2
+ export function negotiateFormat(accept) {
3
+ if (!accept)
4
+ return "html";
5
+ if (!accept.includes("markdown") && !accept.includes("q=")) {
6
+ return accept.includes("html") || accept.includes("*/*") || accept.includes("text/*") ? "html" : null;
7
+ }
8
+ let html = -1;
9
+ let markdown = -1;
10
+ let htmlSpecific = false;
11
+ let markdownSpecific = false;
12
+ for (const range of accept.split(",")) {
13
+ const [rawType = "", ...params] = range.split(";");
14
+ const type = rawType.trim().toLowerCase();
15
+ let q = 1;
16
+ for (const param of params) {
17
+ const [key, value] = param.split("=");
18
+ if (key?.trim() === "q")
19
+ q = Math.min(1, Math.max(0, Number.parseFloat(value ?? "") || 0));
20
+ }
21
+ if (type === "text/markdown") {
22
+ markdown = q;
23
+ markdownSpecific = true;
24
+ }
25
+ else if (HTML_TYPES.has(type)) {
26
+ if (!htmlSpecific || q > html)
27
+ html = q;
28
+ htmlSpecific = true;
29
+ }
30
+ else if (type === "*/*" || type === "text/*") {
31
+ if (!markdownSpecific)
32
+ markdown = Math.max(markdown, q);
33
+ if (!htmlSpecific)
34
+ html = Math.max(html, q);
35
+ }
36
+ }
37
+ if (html <= 0 && markdown <= 0)
38
+ return null;
39
+ return markdown > html ? "markdown" : "html";
40
+ }
package/dist/text.d.ts ADDED
@@ -0,0 +1,4 @@
1
+ export declare function normalizeUnicode(text: string): string;
2
+ export declare function estimateTokens(text: string): number;
3
+ export declare function toMarkdownPath(pathname: string): string;
4
+ export declare function toPagePath(pathname: string): string;
package/dist/text.js ADDED
@@ -0,0 +1,51 @@
1
+ const REPLACEMENTS = {
2
+ "​": "", "‌": "", "‍": "", "": "", "️": "", "⃣": "", "­": "",
3
+ " ": " ", " ": " ", " ": " ",
4
+ "‐": "-", "‑": "-", "–": "-", "—": "--",
5
+ "‘": "'", "’": "'", "‚": "'", "ʼ": "'", "ʻ": "'",
6
+ "“": '"', "”": '"', "„": '"', "«": '"', "»": '"',
7
+ "…": "...", "•": "-", "·": "-", "→": "->", "←": "<-",
8
+ "×": "x", "÷": "/", "≈": "~=", "≥": ">=",
9
+ "¢": "c", "₹": "INR ", "€": "EUR ", "£": "GBP ", "¥": "JPY ",
10
+ "₩": "KRW ", "₽": "RUB ", "₺": "TRY ", "₨": "Rs.", "֏": "AMD ",
11
+ "₼": "AZN ", "৳": "BDT ", "₡": "CRC ", "₾": "GEL ", "₪": "ILS ",
12
+ "₸": "KZT ", "₦": "NGN ", "₱": "PHP ", "฿": "THB ",
13
+ };
14
+ const PATTERN = new RegExp(`[${Object.keys(REPLACEMENTS).join("")}]|[\\u{1D5D4}-\\u{1D607}\\u{1D7EC}-\\u{1D7F5}]`, "gu");
15
+ const FAST_CHECK = /[^\x00-\x7F]/;
16
+ function replace(char) {
17
+ const mapped = REPLACEMENTS[char];
18
+ if (mapped !== undefined)
19
+ return mapped;
20
+ const code = char.codePointAt(0) ?? 0;
21
+ if (code >= 0x1d7ec)
22
+ return String.fromCharCode(code - 0x1d7ec + 48);
23
+ if (code >= 0x1d5ee)
24
+ return String.fromCharCode(code - 0x1d5ee + 97);
25
+ return String.fromCharCode(code - 0x1d5d4 + 65);
26
+ }
27
+ export function normalizeUnicode(text) {
28
+ return FAST_CHECK.test(text) ? text.replace(PATTERN, replace) : text;
29
+ }
30
+ export function estimateTokens(text) {
31
+ let count = 0;
32
+ let inWord = false;
33
+ for (let i = 0; i < text.length; i++) {
34
+ const c = text.charCodeAt(i);
35
+ const space = c === 32 || (c >= 9 && c <= 13);
36
+ if (!space && !inWord)
37
+ count++;
38
+ inWord = !space;
39
+ }
40
+ return count;
41
+ }
42
+ export function toMarkdownPath(pathname) {
43
+ if (pathname.endsWith(".md"))
44
+ return pathname;
45
+ const trimmed = pathname.replace(/\/+$/, "");
46
+ return trimmed === "" ? "/index.md" : `${trimmed}.md`;
47
+ }
48
+ export function toPagePath(pathname) {
49
+ const stripped = pathname.replace(/\.md$/, "").replace(/\/+$/, "");
50
+ return stripped === "" || stripped === "/index" ? "/" : stripped;
51
+ }
@@ -0,0 +1,55 @@
1
+ export type Format = "html" | "markdown";
2
+ export type AgentPurpose = "training" | "search" | "user-action";
3
+ export interface Agent {
4
+ readonly name: string;
5
+ readonly vendor: string;
6
+ readonly purpose: AgentPurpose;
7
+ }
8
+ export interface RenderContext {
9
+ readonly path: string;
10
+ readonly params: Readonly<Record<string, string>>;
11
+ readonly request: Request;
12
+ readonly agent: Agent | null;
13
+ }
14
+ export type Awaitable<T> = T | Promise<T>;
15
+ export type LocalSource = (context: RenderContext) => Awaitable<string | null | undefined>;
16
+ export interface RemoteSource {
17
+ readonly _tag: "remote";
18
+ readonly url: string | ((context: RenderContext) => string);
19
+ readonly headers?: Readonly<Record<string, string>>;
20
+ }
21
+ export type Source = string | LocalSource | RemoteSource;
22
+ export interface AgentMatcher {
23
+ readonly agents?: readonly string[];
24
+ readonly vendors?: readonly string[];
25
+ readonly purposes?: readonly AgentPurpose[];
26
+ }
27
+ export interface Variant extends AgentMatcher {
28
+ readonly id: string;
29
+ readonly source: Source;
30
+ }
31
+ export interface ServeEvent {
32
+ readonly path: string;
33
+ readonly variant: string;
34
+ readonly agent: Agent | null;
35
+ readonly status: number;
36
+ readonly cached: boolean;
37
+ readonly durationMs: number;
38
+ }
39
+ export interface AgentsideConfig {
40
+ readonly routes: Readonly<Record<string, Source>>;
41
+ readonly variants?: Readonly<Record<string, readonly Variant[]>>;
42
+ readonly skip?: readonly string[];
43
+ readonly cache?: {
44
+ readonly ttlMs?: number;
45
+ readonly capacity?: number;
46
+ } | false;
47
+ readonly timeoutMs?: number;
48
+ readonly retries?: number;
49
+ readonly cacheControl?: string;
50
+ readonly noindex?: boolean;
51
+ readonly linkHeader?: boolean;
52
+ readonly normalize?: boolean;
53
+ readonly onServe?: (event: ServeEvent) => void;
54
+ readonly onError?: (error: unknown, path: string) => void;
55
+ }
package/dist/types.js ADDED
@@ -0,0 +1 @@
1
+ export {};
package/package.json CHANGED
@@ -1,6 +1,57 @@
1
1
  {
2
2
  "name": "@usenotra/agentside",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "description": "Serve markdown to AI agents and A/B test what they read. Built on Effect. By Notra.",
5
+ "keywords": [
6
+ "ai",
7
+ "agents",
8
+ "markdown",
9
+ "llms",
10
+ "geo",
11
+ "aeo",
12
+ "content-negotiation",
13
+ "effect"
14
+ ],
15
+ "license": "MIT",
16
+ "homepage": "https://agentside.usenotra.com",
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "git+https://github.com/usenotra/agentside.git",
20
+ "directory": "packages/agentside"
21
+ },
22
+ "type": "module",
23
+ "sideEffects": false,
24
+ "files": [
25
+ "dist"
26
+ ],
27
+ "exports": {
28
+ ".": {
29
+ "types": "./dist/index.d.ts",
30
+ "default": "./dist/index.js"
31
+ },
32
+ "./effect": {
33
+ "types": "./dist/effect.d.ts",
34
+ "default": "./dist/effect.js"
35
+ },
36
+ "./build": {
37
+ "types": "./dist/build.d.ts",
38
+ "default": "./dist/build.js"
39
+ }
40
+ },
41
+ "scripts": {
42
+ "build": "tsc -p tsconfig.build.json",
43
+ "check-types": "tsc --noEmit"
44
+ },
45
+ "peerDependencies": {
46
+ "effect": "^4.1.0"
47
+ },
48
+ "devDependencies": {
49
+ "@types/bun": "1.4.4",
50
+ "effect": "4.1.2",
51
+ "typescript": "7.0.2"
52
+ },
53
+ "publishConfig": {
54
+ "access": "public",
55
+ "provenance": true
56
+ }
57
+ }