llmtxt 2026.4.0

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# Changelog
+
+All notable changes to `llmtxt` will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [2026.4.0] - 2026-03-27
+
+### Added
+- **sdk**: `llmtxt/sdk` subpath export with collaborative document primitives
+- **lifecycle**: `DocumentState` enum (DRAFT, REVIEW, LOCKED, ARCHIVED) and pure state transition validator `isValidTransition()`
+- **lifecycle**: `StateTransition` type with full transition metadata (who, when, why, at which version)
+- **versioning**: `VersionEntry` type and `reconstructVersion()` for rebuilding any version from a patch stack
+- **versioning**: `validatePatchApplies()` for pre-flight patch conflict detection
+- **versioning**: `squashPatches()` to compose consecutive patches into one
+- **attribution**: `ContributorSummary` and `VersionAttribution` types with `buildContributorSummary()` and `attributeVersion()` helpers
+- **consensus**: `ApprovalStatus` enum, `Review`, `ApprovalPolicy` types, and `evaluateApprovals()` pure evaluation logic
+- **storage**: `ContentRef` type abstracting inline blobs vs object-store references
+- **retrieval**: `planRetrieval()` token-budget-aware section planning using disclosure primitives
+- **exports**: tree-shakeable subpath exports for `llmtxt/disclosure`, `llmtxt/similarity`, `llmtxt/graph`
+
+### Changed
+- **package**: renamed from `@codluv/llmtxt` to `llmtxt` (unscoped, shorter imports)
+- **structure**: renamed `packages/core/` to `packages/llmtxt/` to match npm package name
+- **description**: updated to reflect SDK capabilities alongside primitives
+
+## [2026.3.1] - 2026-03-27
+
+### Fixed
+- **signed-url**: `verify_signed_url` now treats `exp=0` as "never expires" instead of immediately expired, aligning with `is_expired()` behavior
+
+## [2026.3.0] - 2026-03-26
+
+### Added
+
+- **patching**: `createPatch` and `applyPatch` unified-diff helpers backed by the Rust core for deterministic attachment versioning workflows
+- **client**: `reshare`, `addVersion`, `addVersionFromContent`, and `createVersionPatch` helpers for attachment lifecycle and version submission
+- **types**: `AttachmentSharingMode`, `AttachmentReshareOptions`, `AttachmentVersionOptions`, and `AttachmentVersionResult` support for consumers integrating attachment APIs
+
+### Changed
+
+- **versioning**: adopt unified ecosystem CalVer across the Rust crate, WASM artifacts, and TypeScript package consumers using a Cargo-safe `YYYY.M.PATCH` format
+- **client**: keep `resign` as a backward-compatible alias while standardizing on `reshare`
+- **signed-url**: support configurable path prefixes and signature lengths when generating URLs
+- **signed-url**: verify URLs using the actual signature length and final path segment so `/attachments/{slug}` URLs verify correctly
+- **build**: add `build:wasm`, `build:all`, and `validate` scripts for release-ready consumer artifacts
+
+## Legacy [0.4.0] - 2026-03-23
+
+### Added
+
+- **compression**: deflate compress/decompress, base62 encoding/decoding, SHA-256 hashing, token estimation, compression ratio calculation
+- **schemas**: Zod validation schemas for JSON/text/markdown formats, `prompt-v1` predefined schema, schema registry with type exports
+- **validation**: format auto-detection, content validation against schemas, `autoValidate` convenience function
+- **disclosure**: progressive disclosure utilities -- document overview generation, section extraction, line-range access, content search (string + regex), JSONPath queries, TOC generation
+- **cache**: generic LRU cache with configurable TTL, max size, and hit/miss statistics
+- **signed-url**: HMAC-SHA256 signed URL generation and verification -- conversation-scoped, time-limited, with timing-safe comparison
+
+[Unreleased]: https://github.com/kryptobaseddev/llmtxt/compare/core-v2026.4.0...HEAD
+[2026.4.0]: https://github.com/kryptobaseddev/llmtxt/releases/tag/core-v2026.4.0
+[2026.3.1]: https://github.com/kryptobaseddev/llmtxt/releases/tag/core-v2026.3.1
+[2026.3.0]: https://github.com/kryptobaseddev/llmtxt/releases/tag/core-v2026.3.0
+[0.4.0]: https://github.com/kryptobaseddev/llmtxt/releases/tag/core-v0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codluv
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,64 @@
+# llmtxt
+
+Primitives and SDK for LLM agent content workflows.
+
+`llmtxt` wraps the Rust `llmtxt-core` crate through WASM so TypeScript
+consumers use the same single-source-of-truth logic as native Rust consumers.
+
+## Install
+
+```bash
+npm install llmtxt
+```
+
+## Primitives
+
+```ts
+import {
+  compress, decompress, generateId, hashContent,
+  createPatch, applyPatch, generateSignedUrl,
+} from 'llmtxt';
+
+const compressed = await compress('Hello world');
+const text = await decompress(compressed);
+const slug = generateId();
+const hash = hashContent(text);
+
+const patch = createPatch('hello\n', 'hello world\n');
+const rebuilt = applyPatch('hello\n', patch);
+```
+
+## SDK (Collaborative Documents)
+
+```ts
+import {
+  isValidTransition, evaluateApprovals, planRetrieval,
+  reconstructVersion, attributeVersion, buildContributorSummary,
+} from 'llmtxt/sdk';
+```
+
+### Subpath Exports
+
+```ts
+import { generateOverview, getSection } from 'llmtxt/disclosure';
+import { textSimilarity, rankBySimilarity } from 'llmtxt/similarity';
+import { buildGraph } from 'llmtxt/graph';
+```
+
+## What Ships
+
+- Compression, hashing, base62, token estimation (Rust WASM)
+- Signed URL generation and verification
+- Unified diff patch creation, application, version reconstruction
+- Progressive disclosure: overview, section extraction, content search
+- Collaborative document lifecycle (DRAFT, REVIEW, LOCKED, ARCHIVED)
+- Version stack management with attribution tracking
+- Consensus/approval evaluation with stale review handling
+- Token-budget-aware retrieval planning
+- Storage content reference abstractions (inline vs object-store)
+- Attachment client helpers for upload, fetch, reshare, versioning
+
+## Release Model
+
+The npm package includes prebuilt WASM artifacts generated from the Rust crate in
+`crates/llmtxt-core`, so TypeScript and Rust consumers stay aligned on behavior.

package/dist/cache.d.ts

@@ -0,0 +1,155 @@
+/**
+ * Generic LRU cache with TTL support and hit/miss statistics.
+ *
+ * Provider-agnostic — no framework dependencies.
+ */
+/**
+ * Snapshot of cache performance statistics.
+ *
+ * @remarks
+ * Returned by {@link LRUCache.getStats}. The `hitRate` is calculated as
+ * `(hits / (hits + misses)) * 100` and rounded to two decimal places.
+ */
+export interface CacheStats {
+    /** Total number of cache hits since last reset. */
+    hits: number;
+    /** Total number of cache misses since last reset. */
+    misses: number;
+    /** Current number of live (non-expired) entries in the cache. */
+    size: number;
+    /** Maximum number of entries the cache can hold. */
+    maxSize: number;
+    /** Hit rate as a percentage (0-100), rounded to two decimal places. */
+    hitRate: number;
+}
+/**
+ * Configuration options for constructing an {@link LRUCache} instance.
+ *
+ * @remarks
+ * All fields are optional and have sensible defaults: 1000 entries max
+ * and a 24-hour TTL.
+ */
+export interface LRUCacheOptions {
+    /** Maximum number of entries before the least-recently-used entry is evicted (default: 1000). */
+    maxSize?: number;
+    /** Default time-to-live in milliseconds for new entries (default: 24 hours). */
+    ttl?: number;
+}
+/**
+ * Generic least-recently-used (LRU) cache with time-to-live support.
+ *
+ * @remarks
+ * Backed by a `Map` whose insertion order doubles as the LRU eviction
+ * order. Expired entries are lazily evicted on access. The cache tracks
+ * hit/miss statistics for observability.
+ *
+ * @typeParam T - The type of cached values.
+ *
+ * @example
+ * ```ts
+ * const cache = new LRUCache<string>({ maxSize: 100, ttl: 60_000 });
+ * cache.set('key', 'value');
+ * cache.get('key'); // "value"
+ * ```
+ */
+export declare class LRUCache<T> {
+    /** Internal map storing cache entries in insertion (LRU) order. */
+    private cache;
+    /** Maximum number of entries before eviction. */
+    private maxSize;
+    /** Default time-to-live in milliseconds for new entries. */
+    private defaultTtl;
+    /** Running hit/miss counters for observability. */
+    private stats;
+    /**
+     * Create a new LRU cache.
+     *
+     * @remarks
+     * When no options are provided the cache defaults to 1000 entries max
+     * and a 24-hour TTL.
+     *
+     * @param options - Optional configuration for max size and TTL.
+     */
+    constructor(options?: LRUCacheOptions);
+    /**
+     * Retrieve a cached value by key.
+     *
+     * @remarks
+     * Returns `undefined` and increments the miss counter when the key is
+     * absent or its entry has expired. On a hit the entry is promoted to
+     * most-recently-used position.
+     *
+     * @param key - The cache key to look up.
+     * @returns The cached value, or `undefined` on miss or expiration.
+     */
+    get(key: string): T | undefined;
+    /**
+     * Insert or update a cache entry.
+     *
+     * @remarks
+     * If the cache is at capacity, the least-recently-used entry is evicted
+     * before the new entry is inserted. An existing entry with the same key
+     * is replaced (and its TTL is reset).
+     *
+     * @param key - The cache key.
+     * @param value - The value to cache.
+     * @param ttl - Optional per-entry TTL in milliseconds (overrides default).
+     */
+    set(key: string, value: T, ttl?: number): void;
+    /**
+     * Remove a single entry from the cache by key.
+     *
+     * @remarks
+     * No-op if the key does not exist. Does not affect hit/miss statistics.
+     *
+     * @param key - The cache key to remove.
+     */
+    delete(key: string): void;
+    /**
+     * Remove all entries from the cache and reset hit/miss statistics.
+     *
+     * @remarks
+     * After calling `clear()`, both the entry map and the hit/miss counters
+     * are zeroed, returning the cache to its initial state.
+     */
+    clear(): void;
+    /**
+     * Return the number of live (non-expired) entries in the cache.
+     *
+     * @remarks
+     * Performs a lazy sweep to remove expired entries before counting.
+     *
+     * @returns The current number of live entries.
+     */
+    size(): number;
+    /**
+     * Check whether a non-expired entry exists for the given key.
+     *
+     * @remarks
+     * Expired entries are lazily evicted during this check. This method does
+     * not promote the entry to most-recently-used position.
+     *
+     * @param key - The cache key to check.
+     * @returns `true` if a live entry exists, `false` otherwise.
+     */
+    has(key: string): boolean;
+    /**
+     * Retrieve a snapshot of cache performance statistics.
+     *
+     * @remarks
+     * Triggers a lazy sweep of expired entries (via {@link LRUCache.size})
+     * so that the reported `size` reflects only live entries.
+     *
+     * @returns A {@link CacheStats} object with hits, misses, size, and hit rate.
+     */
+    getStats(): CacheStats;
+    /**
+     * Reset the hit/miss counters to zero without clearing cached entries.
+     *
+     * @remarks
+     * Useful for measuring hit rate over a specific time window without
+     * evicting any cached data.
+     */
+    resetStats(): void;
+}
+//# sourceMappingURL=cache.d.ts.map

package/dist/cache.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../src/cache.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAOH;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,mDAAmD;IACnD,IAAI,EAAE,MAAM,CAAC;IACb,qDAAqD;IACrD,MAAM,EAAE,MAAM,CAAC;IACf,iEAAiE;IACjE,IAAI,EAAE,MAAM,CAAC;IACb,oDAAoD;IACpD,OAAO,EAAE,MAAM,CAAC;IAChB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAC;CACjB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,eAAe;IAC9B,iGAAiG;IACjG,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,gFAAgF;IAChF,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,qBAAa,QAAQ,CAAC,CAAC;IACrB,mEAAmE;IACnE,OAAO,CAAC,KAAK,CAA6B;IAC1C,iDAAiD;IACjD,OAAO,CAAC,OAAO,CAAS;IACxB,4DAA4D;IAC5D,OAAO,CAAC,UAAU,CAAS;IAC3B,mDAAmD;IACnD,OAAO,CAAC,KAAK,CAAmC;IAEhD;;;;;;;;OAQG;gBACS,OAAO,GAAE,eAAoB;IAOzC;;;;;;;;;;OAUG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,CAAC,GAAG,SAAS;IAsB/B;;;;;;;;;;;OAWG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,CAAC,EAAE,GAAG,CAAC,EAAE,MAAM,GAAG,IAAI;IAmB9C;;;;;;;OAOG;IACH,MAAM,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI;IAIzB;;;;;;OAMG;IACH,KAAK,IAAI,IAAI;IAMb;;;;;;;OAOG;IACH,IAAI,IAAI,MAAM;IAUd;;;;;;;;;OASG;IACH,GAAG,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO;IAUzB;;;;;;;;OAQG;IACH,QAAQ,IAAI,UAAU;IAWtB;;;;;;OAMG;IACH,UAAU,IAAI,IAAI;CAInB"}

package/dist/cache.js

@@ -0,0 +1,193 @@
+/**
+ * Generic LRU cache with TTL support and hit/miss statistics.
+ *
+ * Provider-agnostic — no framework dependencies.
+ */
+/**
+ * Generic least-recently-used (LRU) cache with time-to-live support.
+ *
+ * @remarks
+ * Backed by a `Map` whose insertion order doubles as the LRU eviction
+ * order. Expired entries are lazily evicted on access. The cache tracks
+ * hit/miss statistics for observability.
+ *
+ * @typeParam T - The type of cached values.
+ *
+ * @example
+ * ```ts
+ * const cache = new LRUCache<string>({ maxSize: 100, ttl: 60_000 });
+ * cache.set('key', 'value');
+ * cache.get('key'); // "value"
+ * ```
+ */
+export class LRUCache {
+    /** Internal map storing cache entries in insertion (LRU) order. */
+    cache;
+    /** Maximum number of entries before eviction. */
+    maxSize;
+    /** Default time-to-live in milliseconds for new entries. */
+    defaultTtl;
+    /** Running hit/miss counters for observability. */
+    stats;
+    /**
+     * Create a new LRU cache.
+     *
+     * @remarks
+     * When no options are provided the cache defaults to 1000 entries max
+     * and a 24-hour TTL.
+     *
+     * @param options - Optional configuration for max size and TTL.
+     */
+    constructor(options = {}) {
+        this.cache = new Map();
+        this.maxSize = options.maxSize ?? 1000;
+        this.defaultTtl = options.ttl ?? 24 * 60 * 60 * 1000;
+        this.stats = { hits: 0, misses: 0 };
+    }
+    /**
+     * Retrieve a cached value by key.
+     *
+     * @remarks
+     * Returns `undefined` and increments the miss counter when the key is
+     * absent or its entry has expired. On a hit the entry is promoted to
+     * most-recently-used position.
+     *
+     * @param key - The cache key to look up.
+     * @returns The cached value, or `undefined` on miss or expiration.
+     */
+    get(key) {
+        const entry = this.cache.get(key);
+        if (!entry) {
+            this.stats.misses++;
+            return undefined;
+        }
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            this.stats.misses++;
+            return undefined;
+        }
+        // Move to end (most recently used)
+        this.cache.delete(key);
+        this.cache.set(key, entry);
+        this.stats.hits++;
+        return entry.value;
+    }
+    /**
+     * Insert or update a cache entry.
+     *
+     * @remarks
+     * If the cache is at capacity, the least-recently-used entry is evicted
+     * before the new entry is inserted. An existing entry with the same key
+     * is replaced (and its TTL is reset).
+     *
+     * @param key - The cache key.
+     * @param value - The value to cache.
+     * @param ttl - Optional per-entry TTL in milliseconds (overrides default).
+     */
+    set(key, value, ttl) {
+        const effectiveTtl = ttl ?? this.defaultTtl;
+        const entry = {
+            value,
+            expiresAt: Date.now() + effectiveTtl,
+        };
+        this.cache.delete(key);
+        if (this.cache.size >= this.maxSize) {
+            const firstKey = this.cache.keys().next().value;
+            if (firstKey !== undefined) {
+                this.cache.delete(firstKey);
+            }
+        }
+        this.cache.set(key, entry);
+    }
+    /**
+     * Remove a single entry from the cache by key.
+     *
+     * @remarks
+     * No-op if the key does not exist. Does not affect hit/miss statistics.
+     *
+     * @param key - The cache key to remove.
+     */
+    delete(key) {
+        this.cache.delete(key);
+    }
+    /**
+     * Remove all entries from the cache and reset hit/miss statistics.
+     *
+     * @remarks
+     * After calling `clear()`, both the entry map and the hit/miss counters
+     * are zeroed, returning the cache to its initial state.
+     */
+    clear() {
+        this.cache.clear();
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+    }
+    /**
+     * Return the number of live (non-expired) entries in the cache.
+     *
+     * @remarks
+     * Performs a lazy sweep to remove expired entries before counting.
+     *
+     * @returns The current number of live entries.
+     */
+    size() {
+        const now = Date.now();
+        for (const [key, entry] of this.cache.entries()) {
+            if (now > entry.expiresAt) {
+                this.cache.delete(key);
+            }
+        }
+        return this.cache.size;
+    }
+    /**
+     * Check whether a non-expired entry exists for the given key.
+     *
+     * @remarks
+     * Expired entries are lazily evicted during this check. This method does
+     * not promote the entry to most-recently-used position.
+     *
+     * @param key - The cache key to check.
+     * @returns `true` if a live entry exists, `false` otherwise.
+     */
+    has(key) {
+        const entry = this.cache.get(key);
+        if (!entry)
+            return false;
+        if (Date.now() > entry.expiresAt) {
+            this.cache.delete(key);
+            return false;
+        }
+        return true;
+    }
+    /**
+     * Retrieve a snapshot of cache performance statistics.
+     *
+     * @remarks
+     * Triggers a lazy sweep of expired entries (via {@link LRUCache.size})
+     * so that the reported `size` reflects only live entries.
+     *
+     * @returns A {@link CacheStats} object with hits, misses, size, and hit rate.
+     */
+    getStats() {
+        const total = this.stats.hits + this.stats.misses;
+        return {
+            hits: this.stats.hits,
+            misses: this.stats.misses,
+            size: this.size(),
+            maxSize: this.maxSize,
+            hitRate: total > 0 ? parseFloat(((this.stats.hits / total) * 100).toFixed(2)) : 0,
+        };
+    }
+    /**
+     * Reset the hit/miss counters to zero without clearing cached entries.
+     *
+     * @remarks
+     * Useful for measuring hit rate over a specific time window without
+     * evicting any cached data.
+     */
+    resetStats() {
+        this.stats.hits = 0;
+        this.stats.misses = 0;
+    }
+}
+//# sourceMappingURL=cache.js.map

package/dist/cache.js.map

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

package/dist/client.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Lightweight llmtxt client for agents.
+ * Wraps the ClawMsgr attachment API with typed helpers.
+ * No framework dependencies — uses native fetch.
+ *
+ * When `@cleocode/lafs` is installed, responses are validated
+ * against the LAFS envelope schema. Without it, raw JSON is parsed directly.
+ */
+import type { AttachmentReshareOptions, AttachmentSharingMode, AttachmentVersionOptions } from './types.js';
+export interface LlmtxtClientConfig {
+    apiBase: string;
+    apiKey: string;
+    agentId: string;
+}
+export interface UploadResult {
+    slug: string;
+    contentHash: string;
+    originalSize: number;
+    compressedSize: number;
+    compressionRatio: number;
+    tokens: number;
+    signedUrl: string;
+    expiresAt: number;
+}
+export interface FetchResult {
+    slug: string;
+    content: string;
+    format: string;
+    title?: string;
+    contentHash: string;
+    originalSize: number;
+    tokens: number;
+}
+export interface ReshareResult {
+    slug: string;
+    mode: AttachmentSharingMode;
+    signedUrl?: string;
+    expiresAt?: number | null;
+}
+/** Backward-compatible alias. Prefer `ReshareResult`. */
+export type ResignResult = ReshareResult;
+export interface AttachmentVersionResult {
+    slug: string;
+    versionNumber: number;
+    patchText?: string;
+    contentHash?: string;
+    createdAt?: string;
+    createdBy?: string;
+    changelog?: string;
+}
+export declare function createClient(config: LlmtxtClientConfig): {
+    /** Upload content as an attachment to a conversation. */
+    upload(conversationId: string, content: string, options?: {
+        format?: string;
+        title?: string;
+        expiresIn?: number;
+    }): Promise<UploadResult>;
+    /** Fetch content from a signed URL. */
+    fetch(signedUrl: string): Promise<FetchResult>;
+    /** Fetch an attachment shared in a conversation without needing a signed URL. */
+    fetchFromConversation(slug: string, conversationId: string): Promise<FetchResult>;
+    /** Fetch an attachment owned by the current agent. */
+    fetchOwned(slug: string): Promise<FetchResult>;
+    /**
+     * Change how an attachment is shared. For `signed_url` mode the API may
+     * return a fresh `signedUrl`; for `conversation`/`public` it may not.
+     */
+    reshare(slug: string, options?: AttachmentReshareOptions): Promise<ReshareResult>;
+    /** Backward-compatible alias for older API wording. Prefer `reshare`. */
+    resign(slug: string, options?: AttachmentReshareOptions): Promise<ResignResult>;
+    /** Build a version patch locally using the Rust/WASM core. */
+    createVersionPatch(original: string, updated: string): string;
+    /** Submit a patch as the next version for an attachment slug. */
+    addVersion(slug: string, patchText: string, options?: AttachmentVersionOptions): Promise<AttachmentVersionResult>;
+    /** Convenience helper that diffs local content then appends the new version. */
+    addVersionFromContent(slug: string, original: string, updated: string, options?: AttachmentVersionOptions): Promise<AttachmentVersionResult>;
+    /** Check if a signed URL is still valid without fetching content. */
+    isValid(signedUrl: string): boolean;
+};
+//# sourceMappingURL=client.d.ts.map

package/dist/client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../src/client.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,wBAAwB,EACxB,qBAAqB,EACrB,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,cAAc,EAAE,MAAM,CAAC;IACvB,gBAAgB,EAAE,MAAM,CAAC;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,MAAM,WAAW,WAAW;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,YAAY,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,aAAa;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,qBAAqB,CAAC;IAC5B,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CAC3B;AAED,yDAAyD;AACzD,MAAM,MAAM,YAAY,GAAG,aAAa,CAAC;AAEzC,MAAM,WAAW,uBAAuB;IACtC,IAAI,EAAE,MAAM,CAAC;IACb,aAAa,EAAE,MAAM,CAAC;IACtB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AA0CD,wBAAgB,YAAY,CAAC,MAAM,EAAE,kBAAkB;IAQnD,yDAAyD;2BAEvC,MAAM,WACb,MAAM,YACN;QAAE,MAAM,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,GAC/D,OAAO,CAAC,YAAY,CAAC;IAWxB,uCAAuC;qBAChB,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAMpD,iFAAiF;gCAC/C,MAAM,kBAAkB,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAUvF,sDAAsD;qBAC/B,MAAM,GAAG,OAAO,CAAC,WAAW,CAAC;IAMpD;;;OAGG;kBAEK,MAAM,YACH,wBAAwB,GAChC,OAAO,CAAC,aAAa,CAAC;IAWzB,yEAAyE;iBAEjE,MAAM,YACH,wBAAwB,GAChC,OAAO,CAAC,YAAY,CAAC;IAIxB,8DAA8D;iCACjC,MAAM,WAAW,MAAM,GAAG,MAAM;IAI7D,iEAAiE;qBAEzD,MAAM,aACD,MAAM,YACR,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC;IAUnC,gFAAgF;gCAExE,MAAM,YACF,MAAM,WACP,MAAM,YACN,wBAAwB,GAChC,OAAO,CAAC,uBAAuB,CAAC;IAKnC,qEAAqE;uBAClD,MAAM,GAAG,OAAO;EAWtC"}