@de-otio/trellis 0.4.0

package/dist/lib/graph/types.d.ts

@@ -0,0 +1,480 @@
+/**
+ * Graph Service Types
+ *
+ * All input/output types for the GraphService abstraction layer.
+ * These types are database-agnostic — they work for both local Neo4j
+ * (Docker) and Neo4j AuraDB.
+ */
+/** How a relationship was initially established */
+export type ConnectionMethod = "code" | "import" | "suggestion" | "discovery";
+/** Post broadcast radius — determines which circle tiers can see the post */
+export type PostRadius = "WHISPER" | "NORMAL" | "LOUD" | "SHOUT";
+/** Concentric circle tier (0 = innermost, 3 = outermost) */
+export type CircleTier = 0 | 1 | 2 | 3;
+/** Human-readable tier names */
+export type TierName = "inner" | "closeFriends" | "community" | "ambient";
+/** Node type in the graph */
+export type GraphNodeType = "user" | "entity";
+/** Typed entity-to-entity relationship kinds */
+export type EntityRelationshipType = "PACK_MATE" | "SIBLING" | "PLAYMATE" | "PARENT" | "OFFSPRING" | "WALK_BUDDY";
+/** Ownership role for User-[:OWNS]->Entity edges */
+export type OwnershipRole = "PRIMARY_OWNER" | "CO_OWNER" | "CARETAKER";
+/** Types of user interaction used for scoring */
+export type InteractionType = "view" | "react" | "comment" | "share" | "depth_mode" | "profile_visit" | "content_creation";
+/** Confirmation state for entity-to-entity relationships */
+export type EntityRelationshipStatus = "PENDING" | "CONFIRMED" | "REJECTED";
+/**
+ * Minimal user node stored in the graph.
+ *
+ * SECURITY: No PII (email, name, etc.) is stored in graph nodes.
+ * Only the user ID and role are needed for circle resolution and
+ * permission checks. All PII lives exclusively in Postgres.
+ */
+export interface GraphUser {
+    id: string;
+    role: string;
+}
+/**
+ * Entity node stored in the graph (properties needed for graph-side filtering).
+ *
+ * SECURITY: lat/lng are coarsened to 3 decimal places (~1km precision)
+ * before storage to prevent triangulation attacks. See Finding 15.
+ */
+export interface GraphEntity {
+    id: string;
+    entityType: string;
+    name: string;
+    breed?: string;
+    lifeStage?: string;
+    /** Coarsened latitude (3 decimal places, ~1km precision) */
+    lat?: number;
+    /** Coarsened longitude (3 decimal places, ~1km precision) */
+    lng?: number;
+    /** Whether this entity appears in discovery queries. Default true. */
+    discoverable?: boolean;
+}
+/** Minimal post node stored in the graph (content stays in Postgres) */
+export interface GraphPost {
+    id: string;
+    authorId: string;
+    radius: PostRadius;
+    createdAt: Date;
+}
+/** A scored relationship between a user and a target (user or entity) */
+export interface Relationship {
+    /** Source user ID */
+    userId: string;
+    /** Type of the target node */
+    targetType: GraphNodeType;
+    /** Target node ID */
+    targetId: string;
+    /**
+     * Effective score (manualScore if set, otherwise computedScore).
+     * Range: 0.0 to 1.0
+     */
+    score: number;
+    /** Algorithm-computed score based on interaction signals */
+    computedScore: number;
+    /** User-set manual override (null if not set) */
+    manualScore: number | null;
+    /** Resolved circle tier based on score */
+    tier: CircleTier;
+    /** Total interaction count */
+    interactionCount: number;
+    /** Timestamp of last interaction */
+    lastInteractionAt: Date | null;
+    /** How the relationship was initially created */
+    connectionMethod: ConnectionMethod;
+    /** Whether the target also has a relationship back (user->user only) */
+    reciprocated: boolean;
+    /** When the relationship was created */
+    createdAt: Date;
+}
+/** Input for creating a new relationship */
+export interface CreateRelationshipInput {
+    userId: string;
+    targetType: GraphNodeType;
+    targetId: string;
+    connectionMethod?: ConnectionMethod;
+}
+/** Input for updating a relationship's manual score */
+export interface UpdateRelationshipScoreInput {
+    userId: string;
+    targetType: GraphNodeType;
+    targetId: string;
+    /** Set to a number to override, or null to clear the override */
+    manualScore: number | null;
+}
+/** A member (user or entity) within a circle tier */
+export interface CircleMember {
+    /** Node ID */
+    id: string;
+    /** Whether this is a user or entity */
+    type: GraphNodeType;
+    /** Display name (from graph node) */
+    name: string;
+    /** Relationship score */
+    score: number;
+    /** Resolved tier */
+    tier: CircleTier;
+}
+/** Status of a single circle tier */
+export interface CircleTierStatus {
+    tier: CircleTier;
+    name: TierName;
+    /** Whether all content has been seen */
+    caughtUp: boolean;
+    /** Number of posts not yet seen */
+    unseenCount: number;
+    /** When the user last marked this tier as read */
+    lastReadAt: Date | null;
+}
+/** Per-entity status within a circle tier */
+export interface CircleEntityStatus {
+    entityId: string;
+    entityName: string;
+    /** Whether all content about this entity has been seen */
+    caughtUp: boolean;
+    /** Number of unseen posts about this entity */
+    unseenCount: number;
+    /** Most recent post timestamp for this entity */
+    latestPostAt: Date | null;
+}
+/** Glance mode: one recent item per entity in the circle */
+export interface GlanceItem {
+    /** Entity or user ID this item is about */
+    targetId: string;
+    targetType: GraphNodeType;
+    targetName: string;
+    /** Most recent post ID (fetch content from Postgres) */
+    postId: string;
+    postCreatedAt: Date;
+}
+/** Result of a visible-post-IDs query */
+export interface VisiblePostResult {
+    /** Post ID (fetch content from Postgres) */
+    postId: string;
+    /** When the post was created */
+    createdAt: Date;
+    /**
+     * Tier of the closest relationship through which this post is visible.
+     * For multi-entity posts, this is the minimum tier across all matching subjects.
+     */
+    resolvedTier: CircleTier;
+}
+/** A typed, unscored relationship between two entities */
+export interface EntityRelationship {
+    /** Source entity ID */
+    entityId: string;
+    /** Target entity ID */
+    relatedEntityId: string;
+    /** Relationship type (PACK_MATE, SIBLING, etc.) */
+    type: EntityRelationshipType;
+    /** Confirmation status (requires both owners to confirm) */
+    status: EntityRelationshipStatus;
+    /** User who proposed the relationship */
+    proposedByUserId: string;
+    /** When the relationship was created/proposed */
+    since: Date;
+}
+/** Input for creating an entity-to-entity relationship */
+export interface CreateEntityRelationshipInput {
+    entityId: string;
+    relatedEntityId: string;
+    type: EntityRelationshipType;
+    /** User proposing the relationship (must own entityId) */
+    proposedByUserId: string;
+}
+/**
+ * Filters for multi-hop entity discovery.
+ *
+ * SECURITY: Discovery is rate-limited to 5 requests/minute/user.
+ * Hop count is hard-capped at 2 to prevent graph traversal DoS
+ * (3-hop traversals can visit 100^3 nodes on popular entities).
+ */
+export interface DiscoveryFilters {
+    /** Filter by entity type (e.g., "dog") */
+    entityType?: string;
+    /** Filter by breed */
+    breed?: string;
+    /** Filter by life stage */
+    lifeStage?: string;
+    /**
+     * Number of relationship hops to traverse. Hard-capped at 2.
+     * Server rejects values > 2. Default: 2.
+     */
+    hops?: 1 | 2;
+    /** Maximum number of results */
+    limit?: number;
+}
+/** Filters for spatial (nearby) discovery */
+export interface NearbyFilters {
+    /** Filter by entity type */
+    entityType?: string;
+    /** Filter by breed */
+    breed?: string;
+    /** Maximum number of results */
+    limit?: number;
+}
+/** A discovered entity with distance metadata */
+export interface DiscoveryResult {
+    /** Entity ID (fetch full profile from Postgres) */
+    entityId: string;
+    /** Entity name (from graph node) */
+    name: string;
+    /** Entity type */
+    entityType: string;
+    /** Breed (if available) */
+    breed?: string;
+    /**
+     * Coarse distance band for spatial queries. Exact distance in meters
+     * is only provided when the viewer has an existing relationship (tier 0-2)
+     * with the entity. For unrelated viewers, only the band is returned
+     * to prevent location triangulation.
+     */
+    distanceBand?: "< 500m" | "500m-1km" | "1-2km" | "2-5km" | "> 5km";
+    /**
+     * Exact distance in meters. Only populated when the viewer has an
+     * existing relationship with the entity (tier 0-2). Null for
+     * unrelated viewers (use distanceBand instead).
+     */
+    distanceMeters?: number;
+    /**
+     * How this entity was discovered.
+     * For multi-hop: number of hops from the user's entities.
+     * For spatial: undefined.
+     */
+    hops?: number;
+}
+/** Recommendation based on graph analysis */
+export interface Recommendation {
+    /** Recommended entity ID */
+    entityId: string;
+    /** Entity name */
+    name: string;
+    /** Entity type */
+    entityType: string;
+    /** Why this entity was recommended */
+    reason: RecommendationReason;
+    /** Confidence score (0.0 to 1.0) */
+    confidence: number;
+}
+/**
+ * Reason why an entity was recommended (client-facing).
+ *
+ * SECURITY: `owner_proximity` is intentionally excluded. Exposing it
+ * as a client-facing reason would leak graph topology information
+ * (the viewer could infer that they have a close relationship with the
+ * entity's owner, even if that relationship is not explicitly visible).
+ * Owner proximity is used internally for scoring but mapped to
+ * "shared_connections" in the client-facing response.
+ */
+export type RecommendationReason = "shared_connections" | "same_breed" | "nearby" | "popular_in_circle";
+/** Input for recording a user interaction */
+export interface RecordInteractionInput {
+    userId: string;
+    targetType: GraphNodeType;
+    targetId: string;
+    interactionType: InteractionType;
+    /** Optional metadata (e.g., post ID that triggered the interaction) */
+    metadata?: Record<string, string>;
+}
+/** Scoring weights configuration (target-type-aware) */
+export interface ScoringWeights {
+    /** Engagement depth weight (entity relationships only) */
+    engagement: number;
+    /** Interaction frequency weight */
+    frequency: number;
+    /** Owner proximity weight (entity relationships only) */
+    ownerProximity: number;
+    /** Content creation weight (entity relationships only) */
+    contentCreation: number;
+    /** Connection method initial bonus weight */
+    connection: number;
+    /** Decay penalty weight */
+    decay: number;
+    /** Reciprocity weight (user-to-user relationships only) */
+    reciprocity: number;
+}
+/** Result of a score recomputation */
+export interface ScoreUpdate {
+    userId: string;
+    targetType: GraphNodeType;
+    targetId: string;
+    previousScore: number;
+    newScore: number;
+    previousTier: CircleTier;
+    newTier: CircleTier;
+}
+/** Full relationship graph data for the visualization UI */
+export interface GraphData {
+    /** All relationship targets as graph nodes */
+    nodes: GraphNode[];
+    /** Tier summary statistics */
+    tiers: TierSummary;
+}
+/**
+ * A node in the relationship graph visualization.
+ *
+ * SECURITY: Raw scores are not exposed to the client. Only the tier
+ * and a coarse closeness indicator (0-100 integer) are returned.
+ * This prevents exact score extraction that could be used to infer
+ * the underlying graph topology.
+ */
+export interface GraphNode {
+    id: string;
+    type: GraphNodeType;
+    name: string;
+    /**
+     * Coarse closeness indicator (0-100 integer, bucketed to nearest 10).
+     * NOT the raw relationship score. Used for visual sizing/positioning
+     * in the graph UI without exposing exact scoring internals.
+     */
+    closeness: number;
+    tier: CircleTier;
+}
+/** Summary of tier thresholds and member counts */
+export interface TierSummary {
+    inner: {
+        threshold: number;
+        count: number;
+    };
+    closeFriends: {
+        threshold: number;
+        count: number;
+    };
+    community: {
+        threshold: number;
+        count: number;
+    };
+    ambient: {
+        threshold: number;
+        count: number;
+    };
+}
+/**
+ * Data to sync a User node to the graph.
+ *
+ * SECURITY: No PII is synced to the graph database. Only the user ID
+ * and role are needed for graph queries. Email, name, and other PII
+ * stay in Postgres.
+ */
+export interface SyncUserInput {
+    id: string;
+    role: string;
+}
+/** Data to sync an Entity node to the graph */
+export interface SyncEntityInput {
+    id: string;
+    entityType: string;
+    name: string;
+    breed?: string;
+    lifeStage?: string;
+    lat?: number;
+    lng?: number;
+}
+/** Data to sync a Post node to the graph */
+export interface SyncPostInput {
+    id: string;
+    authorId: string;
+    radius: PostRadius;
+    createdAt: Date;
+}
+/** Data to sync PostSubject edges to the graph */
+export interface SyncPostSubjectsInput {
+    postId: string;
+    /** All entity IDs that this post is about */
+    entityIds: string[];
+    /** The primary entity ID (if any) */
+    primaryEntityId?: string;
+}
+/** Data to sync an EntityOwnership edge to the graph */
+export interface SyncOwnershipInput {
+    entityId: string;
+    userId: string;
+    role: OwnershipRole;
+}
+/** Graph database connection configuration */
+export interface GraphConnectionConfig {
+    /**
+     * Connection endpoint.
+     * - Local (Neo4j Docker): bolt://localhost:7687
+     * - AuraDB: bolt+s://<dbid>.databases.neo4j.io
+     */
+    endpoint: string;
+    /** Authentication mode */
+    auth: GraphAuthConfig;
+    /** Connection pool settings */
+    pool?: GraphPoolConfig;
+    /**
+     * Per-query timeout in milliseconds. Queries exceeding this limit are
+     * aborted to prevent graph traversal DoS. Default: 5000 (5 seconds).
+     * Discovery queries may use a lower value (e.g., 3000).
+     */
+    queryTimeoutMs?: number;
+    /**
+     * Circuit breaker configuration. When the failure rate exceeds the
+     * threshold within the evaluation window, the circuit opens and all
+     * graph queries fail fast (returning cached results or Postgres
+     * fallback) until the recovery period elapses.
+     */
+    circuitBreaker?: GraphCircuitBreakerConfig;
+}
+/** Circuit breaker configuration for graph database queries */
+export interface GraphCircuitBreakerConfig {
+    /** Failure rate threshold (0.0-1.0) to trip the circuit. Default: 0.5 (50%). */
+    failureRateThreshold?: number;
+    /** Number of requests in the evaluation window. Default: 10. */
+    evaluationWindowSize?: number;
+    /** How long the circuit stays open before allowing a probe request, in ms. Default: 30000 (30s). */
+    recoveryPeriodMs?: number;
+    /** Number of successful probe requests needed to close the circuit. Default: 3. */
+    successThreshold?: number;
+}
+/** Authentication configuration */
+export type GraphAuthConfig = {
+    type: "none";
+} | {
+    type: "basic";
+    username: string;
+    password: string;
+};
+/** Connection pool configuration */
+export interface GraphPoolConfig {
+    /** Driver option: maxConnectionPoolSize. Default 100 (driver). */
+    maxConnectionPoolSize?: number;
+    /** Driver option: connectionAcquisitionTimeout. Default 60_000 ms (driver). */
+    connectionAcquisitionTimeout?: number;
+    /** Driver option: maxConnectionLifetime. Default 3_600_000 ms (driver). */
+    maxConnectionLifetime?: number;
+    /** Driver option: connectionLivenessCheckTimeout. Default undefined (disabled). */
+    connectionLivenessCheckTimeout?: number;
+}
+/** Health check result */
+export interface GraphHealthStatus {
+    /** Whether the graph database is reachable and accepting queries */
+    healthy: boolean;
+    /** Round-trip latency of the health check query in milliseconds */
+    latencyMs: number;
+    /** Error message if unhealthy */
+    error?: string;
+    /** Backend type detected */
+    backend: "neo4j" | "unknown";
+}
+/** Cursor-based pagination input */
+export interface PaginationInput {
+    /** Maximum number of results to return */
+    limit: number;
+    /** Opaque cursor from a previous response (omit for first page) */
+    cursor?: string;
+}
+/** Cursor-based pagination output */
+export interface PaginatedResult<T> {
+    /** The result items */
+    items: T[];
+    /** Cursor to fetch the next page (null if no more results) */
+    cursor: string | null;
+    /** Whether more results exist beyond this page */
+    hasMore: boolean;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/graph/types.d.ts.map

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

package/dist/lib/graph/types.js

@@ -0,0 +1,10 @@
+"use strict";
+/**
+ * Graph Service Types
+ *
+ * All input/output types for the GraphService abstraction layer.
+ * These types are database-agnostic — they work for both local Neo4j
+ * (Docker) and Neo4j AuraDB.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/lib/graph/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/lib/graph/types.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG"}

package/dist/lib/hook-dispatcher.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Extension Hook Dispatcher
+ *
+ * Dispatches lifecycle events to registered extensions with:
+ * - 5-second timeout per hook (prevents hung external API calls)
+ * - Circuit breaker (disables after 5 consecutive failures)
+ * - Scoped context (extensions receive ExtensionContext, not Env)
+ * - Fire-and-forget (hook failures never fail core operations)
+ */
+import type { ExtensionHooks } from "@de-otio/trellis-extension-api";
+import type { Env } from "../env";
+/**
+ * Dispatch a lifecycle hook to all registered extensions.
+ *
+ * Core passes env and prisma; the dispatcher creates the scoped
+ * ExtensionContext internally — extensions never see raw Env.
+ */
+export declare function dispatchHook<K extends keyof ExtensionHooks>(hookName: K, env: Env, prisma: any, ...args: any[]): Promise<void>;
+/** Reset circuit breaker state (for testing) */
+export declare function resetHookCircuitBreakers(): void;
+//# sourceMappingURL=hook-dispatcher.d.ts.map

package/dist/lib/hook-dispatcher.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-dispatcher.d.ts","sourceRoot":"","sources":["../../src/lib/hook-dispatcher.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAIrE,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,QAAQ,CAAC;AAUlC;;;;;GAKG;AACH,wBAAsB,YAAY,CAAC,CAAC,SAAS,MAAM,cAAc,EAC/D,QAAQ,EAAE,CAAC,EACX,GAAG,EAAE,GAAG,EACR,MAAM,EAAE,GAAG,EACX,GAAG,IAAI,EAAE,GAAG,EAAE,GACb,OAAO,CAAC,IAAI,CAAC,CAwCf;AAED,gDAAgD;AAChD,wBAAgB,wBAAwB,IAAI,IAAI,CAE/C"}

package/dist/lib/hook-dispatcher.js

@@ -0,0 +1,62 @@
+"use strict";
+/**
+ * Extension Hook Dispatcher
+ *
+ * Dispatches lifecycle events to registered extensions with:
+ * - 5-second timeout per hook (prevents hung external API calls)
+ * - Circuit breaker (disables after 5 consecutive failures)
+ * - Scoped context (extensions receive ExtensionContext, not Env)
+ * - Fire-and-forget (hook failures never fail core operations)
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.dispatchHook = dispatchHook;
+exports.resetHookCircuitBreakers = resetHookCircuitBreakers;
+const extensions_1 = require("../extensions");
+const extension_context_1 = require("./extension-context");
+const logger_1 = require("./logger");
+const HOOK_TIMEOUT_MS = 5_000;
+const MAX_CONSECUTIVE_FAILURES = 5;
+const logger = logger_1.Logger.getInstance();
+// Track consecutive failures per extension per hook
+const failureCounts = new Map();
+/**
+ * Dispatch a lifecycle hook to all registered extensions.
+ *
+ * Core passes env and prisma; the dispatcher creates the scoped
+ * ExtensionContext internally — extensions never see raw Env.
+ */
+async function dispatchHook(hookName, env, prisma, ...args) {
+    for (const ext of (0, extensions_1.getExtensions)()) {
+        const hook = ext.hooks?.[hookName];
+        if (!hook)
+            continue;
+        const key = `${ext.id}:${String(hookName)}`;
+        // Circuit breaker: skip if too many consecutive failures
+        const currentFailures = failureCounts.get(key) ?? 0;
+        if (currentFailures >= MAX_CONSECUTIVE_FAILURES) {
+            continue;
+        }
+        try {
+            const ctx = (0, extension_context_1.createExtensionContext)(ext, env, prisma);
+            await Promise.race([
+                hook(...args, ctx),
+                new Promise((_, reject) => setTimeout(() => reject(new Error(`Hook "${String(hookName)}" timed out after ${HOOK_TIMEOUT_MS}ms`)), HOOK_TIMEOUT_MS)),
+            ]);
+            // Reset on success
+            failureCounts.delete(key);
+        }
+        catch (error) {
+            const count = currentFailures + 1;
+            failureCounts.set(key, count);
+            logger.warn(`Extension "${ext.id}" hook "${String(hookName)}" failed (${count}/${MAX_CONSECUTIVE_FAILURES}):`, error);
+            if (count >= MAX_CONSECUTIVE_FAILURES) {
+                logger.error(`Extension "${ext.id}" hook "${String(hookName)}" disabled after ${MAX_CONSECUTIVE_FAILURES} consecutive failures`);
+            }
+        }
+    }
+}
+/** Reset circuit breaker state (for testing) */
+function resetHookCircuitBreakers() {
+    failureCounts.clear();
+}
+//# sourceMappingURL=hook-dispatcher.js.map

package/dist/lib/hook-dispatcher.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"hook-dispatcher.js","sourceRoot":"","sources":["../../src/lib/hook-dispatcher.ts"],"names":[],"mappings":";AAAA;;;;;;;;GAQG;;AAsBH,oCA6CC;AAGD,4DAEC;AArED,8CAA8C;AAC9C,2DAA6D;AAC7D,qCAAkC;AAGlC,MAAM,eAAe,GAAG,KAAK,CAAC;AAC9B,MAAM,wBAAwB,GAAG,CAAC,CAAC;AAEnC,MAAM,MAAM,GAAG,eAAM,CAAC,WAAW,EAAE,CAAC;AAEpC,oDAAoD;AACpD,MAAM,aAAa,GAAG,IAAI,GAAG,EAAkB,CAAC;AAEhD;;;;;GAKG;AACI,KAAK,UAAU,YAAY,CAChC,QAAW,EACX,GAAQ,EACR,MAAW,EACX,GAAG,IAAW;IAEd,KAAK,MAAM,GAAG,IAAI,IAAA,0BAAa,GAAE,EAAE,CAAC;QAClC,MAAM,IAAI,GAAG,GAAG,CAAC,KAAK,EAAE,CAAC,QAAQ,CAAC,CAAC;QACnC,IAAI,CAAC,IAAI;YAAE,SAAS;QAEpB,MAAM,GAAG,GAAG,GAAG,GAAG,CAAC,EAAE,IAAI,MAAM,CAAC,QAAQ,CAAC,EAAE,CAAC;QAE5C,yDAAyD;QACzD,MAAM,eAAe,GAAG,aAAa,CAAC,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAC;QACpD,IAAI,eAAe,IAAI,wBAAwB,EAAE,CAAC;YAChD,SAAS;QACX,CAAC;QAED,IAAI,CAAC;YACH,MAAM,GAAG,GAAG,IAAA,0CAAsB,EAAC,GAAG,EAAE,GAAG,EAAE,MAAM,CAAC,CAAC;YACrD,MAAM,OAAO,CAAC,IAAI,CAAC;gBAChB,IAAiB,CAAC,GAAG,IAAI,EAAE,GAAG,CAAC;gBAChC,IAAI,OAAO,CAAQ,CAAC,CAAC,EAAE,MAAM,EAAE,EAAE,CAC/B,UAAU,CACR,GAAG,EAAE,CAAC,MAAM,CAAC,IAAI,KAAK,CAAC,SAAS,MAAM,CAAC,QAAQ,CAAC,qBAAqB,eAAe,IAAI,CAAC,CAAC,EAC1F,eAAe,CAChB,CACF;aACF,CAAC,CAAC;YACH,mBAAmB;YACnB,aAAa,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QAC5B,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,MAAM,KAAK,GAAG,eAAe,GAAG,CAAC,CAAC;YAClC,aAAa,CAAC,GAAG,CAAC,GAAG,EAAE,KAAK,CAAC,CAAC;YAC9B,MAAM,CAAC,IAAI,CACT,cAAc,GAAG,CAAC,EAAE,WAAW,MAAM,CAAC,QAAQ,CAAC,aAAa,KAAK,IAAI,wBAAwB,IAAI,EACjG,KAAK,CACN,CAAC;YACF,IAAI,KAAK,IAAI,wBAAwB,EAAE,CAAC;gBACtC,MAAM,CAAC,KAAK,CACV,cAAc,GAAG,CAAC,EAAE,WAAW,MAAM,CAAC,QAAQ,CAAC,oBAAoB,wBAAwB,uBAAuB,CACnH,CAAC;YACJ,CAAC;QACH,CAAC;IACH,CAAC;AACH,CAAC;AAED,gDAAgD;AAChD,SAAgB,wBAAwB;IACtC,aAAa,CAAC,KAAK,EAAE,CAAC;AACxB,CAAC"}

package/dist/lib/id-generator.d.ts

@@ -0,0 +1,29 @@
+/**
+ * ID Generator Utilities
+ *
+ * Generates secure, collision-resistant IDs for AT Protocol rkeys.
+ * Uses crypto.randomUUID() for security and collision resistance.
+ */
+/**
+ * ID Generator class for generating secure random IDs
+ */
+export declare class IdGenerator {
+    /**
+     * Generate a secure, random ID suitable for AT Protocol rkeys
+     *
+     * AT Protocol rkeys should be:
+     * - URL-safe (no special characters)
+     * - Collision-resistant
+     * - Unpredictable (security)
+     * - Short enough for URLs
+     *
+     * Format: base64url-encoded random bytes (22 characters)
+     */
+    generateRkey(): string;
+    /**
+     * Generate a prefixed ID (e.g., "dog-abc123")
+     * Useful for namespacing different record types
+     */
+    generatePrefixedRkey(prefix: string): string;
+}
+//# sourceMappingURL=id-generator.d.ts.map

package/dist/lib/id-generator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"id-generator.d.ts","sourceRoot":"","sources":["../../src/lib/id-generator.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH;;GAEG;AACH,qBAAa,WAAW;IACtB;;;;;;;;;;OAUG;IACH,YAAY,IAAI,MAAM;IAgBtB;;;OAGG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM;CAU7C"}