@lobu/connector-sdk 6.0.1

package/dist/event-taxonomy.js

@@ -0,0 +1,30 @@
+export const SOURCE_NATIVE_EVENT_TYPES = [
+    'article',
+    'ask_hn',
+    'comment',
+    'commit',
+    'discussion',
+    'email',
+    'file',
+    'issue',
+    'issue_comment',
+    'message',
+    'photo',
+    'post',
+    'pr_comment',
+    'pull_request',
+    'reply',
+    'repository',
+    'review',
+    'section',
+    'show_hn',
+    'story',
+    'thread',
+    'tweet',
+    'video',
+];
+const SOURCE_NATIVE_EVENT_TYPE_SET = new Set(SOURCE_NATIVE_EVENT_TYPES);
+export function isSourceNativeEventType(value) {
+    return typeof value === 'string' && SOURCE_NATIVE_EVENT_TYPE_SET.has(value);
+}
+//# sourceMappingURL=event-taxonomy.js.map

package/dist/event-taxonomy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"event-taxonomy.js","sourceRoot":"","sources":["../src/event-taxonomy.ts"],"names":[],"mappings":"AAAA,MAAM,CAAC,MAAM,yBAAyB,GAAG;IACvC,SAAS;IACT,QAAQ;IACR,SAAS;IACT,QAAQ;IACR,YAAY;IACZ,OAAO;IACP,MAAM;IACN,OAAO;IACP,eAAe;IACf,SAAS;IACT,OAAO;IACP,MAAM;IACN,YAAY;IACZ,cAAc;IACd,OAAO;IACP,YAAY;IACZ,QAAQ;IACR,SAAS;IACT,SAAS;IACT,OAAO;IACP,QAAQ;IACR,OAAO;IACP,OAAO;CACC,CAAC;AAEX,MAAM,4BAA4B,GAAG,IAAI,GAAG,CAAS,yBAAyB,CAAC,CAAC;AAEhF,MAAM,UAAU,uBAAuB,CAAC,KAAgC;IACtE,OAAO,OAAO,KAAK,KAAK,QAAQ,IAAI,4BAA4B,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC;AAC9E,CAAC"}

package/dist/http.d.ts

@@ -0,0 +1,18 @@
+import { type KyInstance, type Options } from 'ky';
+/**
+ * Create a configured ky instance with custom options
+ */
+export declare function createHttpClient(options?: Options): KyInstance;
+/**
+ * Default HTTP client for feeds with standard User-Agent
+ */
+export declare const httpClient: KyInstance;
+/**
+ * Create an HTTP client with authentication headers
+ */
+export declare function createAuthenticatedClient(authHeader: string, additionalHeaders?: Record<string, string>): KyInstance;
+/**
+ * HTTP client for JSON APIs
+ */
+export declare const jsonHttpClient: KyInstance;
+//# sourceMappingURL=http.d.ts.map

package/dist/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAW,EAAE,KAAK,UAAU,EAAE,KAAK,OAAO,EAAE,MAAM,IAAI,CAAC;AA8BvD;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,OAAO,CAAC,EAAE,OAAO,GAAG,UAAU,CAY9D;AAED;;GAEG;AACH,eAAO,MAAM,UAAU,YAIrB,CAAC;AAEH;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,UAAU,EAAE,MAAM,EAClB,iBAAiB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GACzC,UAAU,CAQZ;AAED;;GAEG;AACH,eAAO,MAAM,cAAc,YAMzB,CAAC"}

package/dist/http.js

@@ -0,0 +1,74 @@
+import ky from 'ky';
+/**
+ * Shared HTTP client configuration for all feeds
+ */
+/**
+ * Default retry configuration
+ * - Max 2 retries (3 total attempts)
+ * - Only retry transient errors (429, 5xx)
+ * - Exponential backoff up to 5 seconds
+ * - 30s timeout per request
+ */
+const defaultRetryConfig = {
+    retry: {
+        limit: 2, // Max 2 retries (3 total attempts)
+        methods: ['get', 'post'],
+        statusCodes: [
+            408, // Request Timeout
+            429, // Too Many Requests (rate limit)
+            500, // Internal Server Error
+            502, // Bad Gateway
+            503, // Service Unavailable
+            504, // Gateway Timeout
+        ],
+        backoffLimit: 5000, // Max 5 seconds delay between retries
+    },
+    timeout: 30000, // 30 second timeout per request
+};
+/**
+ * Create a configured ky instance with custom options
+ */
+export function createHttpClient(options) {
+    return ky.create({
+        ...defaultRetryConfig,
+        ...options,
+        // Merge retry config if provided
+        retry: options?.retry
+            ? {
+                ...defaultRetryConfig.retry,
+                ...(typeof options.retry === 'number' ? { limit: options.retry } : options.retry),
+            }
+            : defaultRetryConfig.retry,
+    });
+}
+/**
+ * Default HTTP client for feeds with standard User-Agent
+ */
+export const httpClient = createHttpClient({
+    headers: {
+        'User-Agent': 'UserResearchBot/1.0',
+    },
+});
+/**
+ * Create an HTTP client with authentication headers
+ */
+export function createAuthenticatedClient(authHeader, additionalHeaders) {
+    return createHttpClient({
+        headers: {
+            'User-Agent': 'UserResearchBot/1.0',
+            Authorization: authHeader,
+            ...additionalHeaders,
+        },
+    });
+}
+/**
+ * HTTP client for JSON APIs
+ */
+export const jsonHttpClient = createHttpClient({
+    headers: {
+        'User-Agent': 'UserResearchBot/1.0',
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+    },
+});
+//# sourceMappingURL=http.js.map

package/dist/http.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.js","sourceRoot":"","sources":["../src/http.ts"],"names":[],"mappings":"AAAA,OAAO,EAAqC,MAAM,IAAI,CAAC;AAEvD;;GAEG;AAEH;;;;;;GAMG;AACH,MAAM,kBAAkB,GAAG;IACzB,KAAK,EAAE;QACL,KAAK,EAAE,CAAC,EAAE,mCAAmC;QAC7C,OAAO,EAAE,CAAC,KAAK,EAAE,MAAM,CAAC;QACxB,WAAW,EAAE;YACX,GAAG,EAAE,kBAAkB;YACvB,GAAG,EAAE,iCAAiC;YACtC,GAAG,EAAE,wBAAwB;YAC7B,GAAG,EAAE,cAAc;YACnB,GAAG,EAAE,sBAAsB;YAC3B,GAAG,EAAE,kBAAkB;SACxB;QACD,YAAY,EAAE,IAAI,EAAE,sCAAsC;KAC3D;IACD,OAAO,EAAE,KAAK,EAAE,gCAAgC;CACjD,CAAC;AAEF;;GAEG;AACH,MAAM,UAAU,gBAAgB,CAAC,OAAiB;IAChD,OAAO,EAAE,CAAC,MAAM,CAAC;QACf,GAAG,kBAAkB;QACrB,GAAG,OAAO;QACV,iCAAiC;QACjC,KAAK,EAAE,OAAO,EAAE,KAAK;YACnB,CAAC,CAAC;gBACE,GAAG,kBAAkB,CAAC,KAAK;gBAC3B,GAAG,CAAC,OAAO,OAAO,CAAC,KAAK,KAAK,QAAQ,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,OAAO,CAAC,KAAK,EAAE,CAAC,CAAC,CAAC,OAAO,CAAC,KAAK,CAAC;aAClF;YACH,CAAC,CAAC,kBAAkB,CAAC,KAAK;KAC7B,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,gBAAgB,CAAC;IACzC,OAAO,EAAE;QACP,YAAY,EAAE,qBAAqB;KACpC;CACF,CAAC,CAAC;AAEH;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,UAAkB,EAClB,iBAA0C;IAE1C,OAAO,gBAAgB,CAAC;QACtB,OAAO,EAAE;YACP,YAAY,EAAE,qBAAqB;YACnC,aAAa,EAAE,UAAU;YACzB,GAAG,iBAAiB;SACrB;KACF,CAAC,CAAC;AACL,CAAC;AAED;;GAEG;AACH,MAAM,CAAC,MAAM,cAAc,GAAG,gBAAgB,CAAC;IAC7C,OAAO,EAAE;QACP,YAAY,EAAE,qBAAqB;QACnC,MAAM,EAAE,kBAAkB;QAC1B,cAAc,EAAE,kBAAkB;KACnC;CACF,CAAC,CAAC"}

package/dist/identity-normalize.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Canonical normalization for identity values written to entity_identities.
+ *
+ * Connectors call these before emitting identifiers on events. The ingestion
+ * pipeline also re-runs normalization as a defensive pass, so mismatched
+ * connector behavior can't poison cross-channel matching.
+ */
+/**
+ * Return the E.164-style digit string for a phone number, or null when the
+ * input doesn't look like a phone. Strips all non-digit characters (including
+ * the leading `+`); does not attempt country-code inference.
+ *
+ * Connectors should pass in values that already represent a specific E.164
+ * number. The normalizer's job is cleanup (spaces, dashes, parens, `+`),
+ * not country-code guessing.
+ */
+export declare function normalizePhone(raw: string | null | undefined): string | null;
+export declare function normalizeEmail(raw: string | null | undefined): string | null;
+/**
+ * WhatsApp JIDs carry one of these suffixes:
+ *   @s.whatsapp.net   — individual, backed by an e164 phone
+ *   @lid              — privacy-protected individual (no phone)
+ *   @g.us             — group chat
+ *   @broadcast        — broadcast list
+ *   @newsletter       — channel / newsletter
+ *
+ * Multi-device messages arrive with a device suffix: `14155551234:5@s.whatsapp.net`.
+ * We strip it so the same person on phone + linked devices collapses to one
+ * identity. We lowercase, trim, and validate shape; invalid inputs return null.
+ * This is a *cleanup* function, not a person-vs-non-person filter — callers
+ * decide whether a normalized wa_jid is appropriate to use as a member identity.
+ */
+export declare function normalizeWaJid(raw: string | null | undefined): string | null;
+/**
+ * Slack user IDs aren't globally unique — two workspaces can both have
+ * `U12345`. Prefix with the workspace (team) id so identities don't bleed
+ * across orgs: `T0XYZ:U12345`.
+ */
+export declare function normalizeSlackUserId(teamId: string | null | undefined, userId: string | null | undefined): string | null;
+export declare function normalizeGithubLogin(raw: string | null | undefined): string | null;
+export declare function normalizeGoogleContactId(raw: string | null | undefined): string | null;
+/**
+ * Normalize `auth_user_id` (Better Auth user id). Trim + lowercase so the
+ * same user id from different clients collapses consistently.
+ */
+export declare function normalizeAuthUserId(raw: string | null | undefined): string | null;
+/**
+ * Look up the normalizer for a given namespace. Returns a noop-trimmer when
+ * the namespace is unknown so custom connector namespaces still get basic
+ * hygiene without special-casing.
+ */
+export declare function normalizeIdentifier(namespace: string, raw: string | null | undefined): string | null;
+//# sourceMappingURL=identity-normalize.d.ts.map

package/dist/identity-normalize.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-normalize.d.ts","sourceRoot":"","sources":["../src/identity-normalize.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAKH;;;;;;;;GAQG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAK5E;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAa5E;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAS5E;AAED;;;;GAIG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,EACjC,MAAM,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAChC,MAAM,GAAG,IAAI,CAOf;AAED,wBAAgB,oBAAoB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAMlF;AAED,wBAAgB,wBAAwB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAKtF;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAAG,MAAM,GAAG,IAAI,CAKjF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,SAAS,EAAE,MAAM,EACjB,GAAG,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,GAC7B,MAAM,GAAG,IAAI,CAoBf"}

package/dist/identity-normalize.js

@@ -0,0 +1,146 @@
+/**
+ * Canonical normalization for identity values written to entity_identities.
+ *
+ * Connectors call these before emitting identifiers on events. The ingestion
+ * pipeline also re-runs normalization as a defensive pass, so mismatched
+ * connector behavior can't poison cross-channel matching.
+ */
+const PHONE_MIN_DIGITS = 7;
+const PHONE_MAX_DIGITS = 15;
+/**
+ * Return the E.164-style digit string for a phone number, or null when the
+ * input doesn't look like a phone. Strips all non-digit characters (including
+ * the leading `+`); does not attempt country-code inference.
+ *
+ * Connectors should pass in values that already represent a specific E.164
+ * number. The normalizer's job is cleanup (spaces, dashes, parens, `+`),
+ * not country-code guessing.
+ */
+export function normalizePhone(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const digits = raw.replace(/\D+/g, '');
+    if (digits.length < PHONE_MIN_DIGITS || digits.length > PHONE_MAX_DIGITS)
+        return null;
+    return digits;
+}
+export function normalizeEmail(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    const atIndex = trimmed.indexOf('@');
+    if (atIndex <= 0 || atIndex === trimmed.length - 1)
+        return null;
+    if (trimmed.indexOf('@', atIndex + 1) !== -1)
+        return null;
+    const local = trimmed.slice(0, atIndex);
+    const domain = trimmed.slice(atIndex + 1);
+    if (!local || !domain)
+        return null;
+    if (domain.indexOf('.') === -1)
+        return null;
+    if (/\s/.test(trimmed))
+        return null;
+    return trimmed;
+}
+/**
+ * WhatsApp JIDs carry one of these suffixes:
+ *   @s.whatsapp.net   — individual, backed by an e164 phone
+ *   @lid              — privacy-protected individual (no phone)
+ *   @g.us             — group chat
+ *   @broadcast        — broadcast list
+ *   @newsletter       — channel / newsletter
+ *
+ * Multi-device messages arrive with a device suffix: `14155551234:5@s.whatsapp.net`.
+ * We strip it so the same person on phone + linked devices collapses to one
+ * identity. We lowercase, trim, and validate shape; invalid inputs return null.
+ * This is a *cleanup* function, not a person-vs-non-person filter — callers
+ * decide whether a normalized wa_jid is appropriate to use as a member identity.
+ */
+export function normalizeWaJid(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    const match = trimmed.match(/^([a-z0-9._-]+)(?::\d+)?@(s\.whatsapp\.net|lid|g\.us|broadcast|newsletter)$/i);
+    if (!match)
+        return null;
+    return `${match[1]}@${match[2]}`;
+}
+/**
+ * Slack user IDs aren't globally unique — two workspaces can both have
+ * `U12345`. Prefix with the workspace (team) id so identities don't bleed
+ * across orgs: `T0XYZ:U12345`.
+ */
+export function normalizeSlackUserId(teamId, userId) {
+    if (typeof teamId !== 'string' || typeof userId !== 'string')
+        return null;
+    const t = teamId.trim();
+    const u = userId.trim();
+    if (!t || !u)
+        return null;
+    if (!/^[a-z0-9_-]+$/i.test(t) || !/^[a-z0-9_-]+$/i.test(u))
+        return null;
+    return `${t}:${u}`.toUpperCase();
+}
+export function normalizeGithubLogin(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim().toLowerCase();
+    if (!trimmed)
+        return null;
+    if (!/^[a-z0-9](?:[a-z0-9]|-(?=[a-z0-9])){0,38}$/.test(trimmed))
+        return null;
+    return trimmed;
+}
+export function normalizeGoogleContactId(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    return trimmed;
+}
+/**
+ * Normalize `auth_user_id` (Better Auth user id). Trim + lowercase so the
+ * same user id from different clients collapses consistently.
+ */
+export function normalizeAuthUserId(raw) {
+    if (typeof raw !== 'string')
+        return null;
+    const trimmed = raw.trim();
+    if (!trimmed)
+        return null;
+    return trimmed;
+}
+/**
+ * Look up the normalizer for a given namespace. Returns a noop-trimmer when
+ * the namespace is unknown so custom connector namespaces still get basic
+ * hygiene without special-casing.
+ */
+export function normalizeIdentifier(namespace, raw) {
+    switch (namespace) {
+        case 'phone':
+            return normalizePhone(raw);
+        case 'email':
+            return normalizeEmail(raw);
+        case 'wa_jid':
+            return normalizeWaJid(raw);
+        case 'github_login':
+            return normalizeGithubLogin(raw);
+        case 'google_contact_id':
+            return normalizeGoogleContactId(raw);
+        case 'auth_user_id':
+            return normalizeAuthUserId(raw);
+        default: {
+            if (typeof raw !== 'string')
+                return null;
+            const trimmed = raw.trim();
+            return trimmed ? trimmed : null;
+        }
+    }
+}
+//# sourceMappingURL=identity-normalize.js.map

package/dist/identity-normalize.js.map

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

package/dist/identity-types.d.ts

@@ -0,0 +1,214 @@
+/**
+ * Identity-engine SDK contracts.
+ *
+ * Connectors emit `ConnectorFact[]` for the authenticated subject; catalog
+ * YAMLs declare `AutoCreateWhenRule[]` on relationship types; the engine
+ * matches facts against rules and writes derivations.
+ *
+ * Schemas are TypeBox so they double as runtime validators at every write
+ * boundary (seeder, engine, MCP tools). Validation is mandatory — the
+ * collapsed model puts a lot in `metadata jsonb`, so without validation the
+ * engine silently corrupts on malformed input.
+ */
+import { type Static } from '@sinclair/typebox';
+/**
+ * How strongly the connector vouches for a fact. Rules require a minimum
+ * assurance to fire. The order is total: `oauth_verified_admin_role` >
+ * `oauth_verified` > `cookie_session` > `self_attested`.
+ */
+export declare const AssuranceLevel: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"oauth_verified_admin_role">, import("@sinclair/typebox").TLiteral<"oauth_verified">, import("@sinclair/typebox").TLiteral<"cookie_session">, import("@sinclair/typebox").TLiteral<"self_attested">]>;
+export type AssuranceLevel = Static<typeof AssuranceLevel>;
+export declare function assuranceMeets(actual: AssuranceLevel, required: AssuranceLevel): boolean;
+export declare const ConnectorFact: import("@sinclair/typebox").TObject<{
+    /** The attribute kind. Each connector declares which namespaces it produces. */
+    namespace: import("@sinclair/typebox").TString;
+    /** Raw value as the provider returned it. Audit-friendly. */
+    identifier: import("@sinclair/typebox").TString;
+    /**
+     * Canonicalised form used for index lookups. Connectors run normalize* on
+     * the value before emitting; the engine re-normalises defensively.
+     */
+    normalizedValue: import("@sinclair/typebox").TString;
+    /** How the connector verified this fact. */
+    assurance: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"oauth_verified_admin_role">, import("@sinclair/typebox").TLiteral<"oauth_verified">, import("@sinclair/typebox").TLiteral<"cookie_session">, import("@sinclair/typebox").TLiteral<"self_attested">]>;
+    /**
+     * Provider's immutable account identifier — the primary binding key
+     * that survives email changes and account-row reissues.
+     */
+    providerStableId: import("@sinclair/typebox").TString;
+    /**
+     * Which connector account row produced this fact. Lets the engine diff
+     * facts per session for revocation.
+     */
+    sourceAccountId: import("@sinclair/typebox").TString;
+    /** ISO-8601 timestamp. Optional; required for high-assurance facts in production. */
+    validTo: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    /**
+     * Optional human-readable note about trust caveats this fact carries.
+     * Surfaced in audit logs and admin UIs; never used by the engine.
+     */
+    notes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type ConnectorFact = Static<typeof ConnectorFact>;
+/**
+ * Each connector exports a static capability declaration. CI lints that the
+ * namespaces it actually emits at runtime are a subset of `produces`.
+ */
+export declare const ConnectorIdentityCapability: import("@sinclair/typebox").TObject<{
+    connectorKey: import("@sinclair/typebox").TString;
+    produces: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        namespace: import("@sinclair/typebox").TString;
+        assurance: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"oauth_verified_admin_role">, import("@sinclair/typebox").TLiteral<"oauth_verified">, import("@sinclair/typebox").TLiteral<"cookie_session">, import("@sinclair/typebox").TLiteral<"self_attested">]>;
+        notes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+}>;
+export type ConnectorIdentityCapability = Static<typeof ConnectorIdentityCapability>;
+/**
+ * `unique_only` rejects ambiguity (writes a collision event for admin
+ * resolution); `all_matches` fans out to every match and is only safe for
+ * weak relationships. `first_match` is deliberately excluded — silently
+ * picking a winner on collision would open adoption-takeover paths.
+ */
+export declare const MatchStrategy: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"unique_only">, import("@sinclair/typebox").TLiteral<"all_matches">]>;
+export type MatchStrategy = Static<typeof MatchStrategy>;
+export declare const AutoCreateWhenRule: import("@sinclair/typebox").TObject<{
+    /** The fact namespace this rule listens for. */
+    sourceNamespace: import("@sinclair/typebox").TString;
+    /**
+     * The metadata field on the target entity-type whose normalized value
+     * must equal the fact's normalizedValue.
+     */
+    targetField: import("@sinclair/typebox").TString;
+    /**
+     * Minimum assurance the fact must carry to fire this rule. The engine
+     * enforces `assuranceMeets(fact.assurance, rule.assuranceRequired)`.
+     */
+    assuranceRequired: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"oauth_verified_admin_role">, import("@sinclair/typebox").TLiteral<"oauth_verified">, import("@sinclair/typebox").TLiteral<"cookie_session">, import("@sinclair/typebox").TLiteral<"self_attested">]>;
+    matchStrategy: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"unique_only">, import("@sinclair/typebox").TLiteral<"all_matches">]>;
+    /**
+     * Optional notes for review tooling — not consumed by the engine.
+     */
+    notes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type AutoCreateWhenRule = Static<typeof AutoCreateWhenRule>;
+/**
+ * The shape stored on `entity_relationship_types.metadata`. Includes the
+ * declared rules plus a version+hash so derivations can pin to the rule
+ * version that fired them and reconciliation can detect drift.
+ */
+export declare const RelationshipTypeIdentityMetadata: import("@sinclair/typebox").TObject<{
+    autoCreateWhen: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TObject<{
+        /** The fact namespace this rule listens for. */
+        sourceNamespace: import("@sinclair/typebox").TString;
+        /**
+         * The metadata field on the target entity-type whose normalized value
+         * must equal the fact's normalizedValue.
+         */
+        targetField: import("@sinclair/typebox").TString;
+        /**
+         * Minimum assurance the fact must carry to fire this rule. The engine
+         * enforces `assuranceMeets(fact.assurance, rule.assuranceRequired)`.
+         */
+        assuranceRequired: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"oauth_verified_admin_role">, import("@sinclair/typebox").TLiteral<"oauth_verified">, import("@sinclair/typebox").TLiteral<"cookie_session">, import("@sinclair/typebox").TLiteral<"self_attested">]>;
+        matchStrategy: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"unique_only">, import("@sinclair/typebox").TLiteral<"all_matches">]>;
+        /**
+         * Optional notes for review tooling — not consumed by the engine.
+         */
+        notes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    }>>;
+    /** Monotonically increasing per relationship-type. Bumped by the seeder on every YAML change. */
+    ruleVersion: import("@sinclair/typebox").TInteger;
+    /** sha256 of the canonicalised auto_create_when array. Drift detection. */
+    ruleHash: import("@sinclair/typebox").TString;
+}>;
+export type RelationshipTypeIdentityMetadata = Static<typeof RelationshipTypeIdentityMetadata>;
+/**
+ * Stored on `events.metadata` for `semantic_type='identity_fact'` rows.
+ *
+ * Tombstone facts (written when a connector refresh stops emitting a
+ * namespace) carry empty `identifier`/`normalizedValue`/`providerStableId`,
+ * which is why those fields allow empty strings here even though
+ * `ConnectorFact` (the connector-side input) requires non-empty.
+ */
+export declare const FactEventMetadata: import("@sinclair/typebox").TObject<{
+    namespace: import("@sinclair/typebox").TString;
+    identifier: import("@sinclair/typebox").TString;
+    normalizedValue: import("@sinclair/typebox").TString;
+    assurance: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"oauth_verified_admin_role">, import("@sinclair/typebox").TLiteral<"oauth_verified">, import("@sinclair/typebox").TLiteral<"cookie_session">, import("@sinclair/typebox").TLiteral<"self_attested">]>;
+    providerStableId: import("@sinclair/typebox").TString;
+    sourceAccountId: import("@sinclair/typebox").TString;
+    /** ISO-8601 timestamp string. Optional; required for high-assurance facts in production. */
+    validTo: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+    notes: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TString>;
+}>;
+export type FactEventMetadata = Static<typeof FactEventMetadata>;
+export declare const DerivedFromProvenance: import("@sinclair/typebox").TObject<{
+    /** events.id of the fact that produced this derivation. */
+    sourceEventId: import("@sinclair/typebox").TInteger;
+    /** Which relationship-type rule fired (entity_relationship_types.id). */
+    relationshipTypeId: import("@sinclair/typebox").TInteger;
+    /** Snapshot of the rule version that fired. Drift signal for reconcile. */
+    ruleVersion: import("@sinclair/typebox").TInteger;
+    /** Hash matching ruleHash on the relationship-type at fire time. */
+    ruleHash: import("@sinclair/typebox").TString;
+    /** Echoed for fast assurance audits without joining back to the event. */
+    factAssurance: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"oauth_verified_admin_role">, import("@sinclair/typebox").TLiteral<"oauth_verified">, import("@sinclair/typebox").TLiteral<"cookie_session">, import("@sinclair/typebox").TLiteral<"self_attested">]>;
+    /** ISO-8601 timestamp. Echoes events.created_at; convenience for relationship-only audits. */
+    derivedAt: import("@sinclair/typebox").TString;
+}>;
+export type DerivedFromProvenance = Static<typeof DerivedFromProvenance>;
+/**
+ * The metadata blob stored on entity_relationships.metadata for derived
+ * rows. Closed shape — extra keys are rejected so the engine can never
+ * accidentally land junk alongside the provenance.
+ */
+export declare const DerivedRelationshipMetadata: import("@sinclair/typebox").TObject<{
+    derivedFrom: import("@sinclair/typebox").TObject<{
+        /** events.id of the fact that produced this derivation. */
+        sourceEventId: import("@sinclair/typebox").TInteger;
+        /** Which relationship-type rule fired (entity_relationship_types.id). */
+        relationshipTypeId: import("@sinclair/typebox").TInteger;
+        /** Snapshot of the rule version that fired. Drift signal for reconcile. */
+        ruleVersion: import("@sinclair/typebox").TInteger;
+        /** Hash matching ruleHash on the relationship-type at fire time. */
+        ruleHash: import("@sinclair/typebox").TString;
+        /** Echoed for fast assurance audits without joining back to the event. */
+        factAssurance: import("@sinclair/typebox").TUnion<[import("@sinclair/typebox").TLiteral<"oauth_verified_admin_role">, import("@sinclair/typebox").TLiteral<"oauth_verified">, import("@sinclair/typebox").TLiteral<"cookie_session">, import("@sinclair/typebox").TLiteral<"self_attested">]>;
+        /** ISO-8601 timestamp. Echoes events.created_at; convenience for relationship-only audits. */
+        derivedAt: import("@sinclair/typebox").TString;
+    }>;
+}>;
+export type DerivedRelationshipMetadata = Static<typeof DerivedRelationshipMetadata>;
+/**
+ * When a fact match would adopt a `$member` row that's already bound to a
+ * different user (or vice versa), the engine writes a pending-approval event
+ * with this shape. Resolution = a privileged user flips
+ * `interaction_status='approved'` after merging entities, or 'rejected' to
+ * dismiss without action.
+ */
+export declare const ClaimCollisionPayload: import("@sinclair/typebox").TObject<{
+    kind: import("@sinclair/typebox").TLiteral<"identity_match">;
+    namespace: import("@sinclair/typebox").TString;
+    identifier: import("@sinclair/typebox").TString;
+    normalizedValue: import("@sinclair/typebox").TString;
+    /**
+     * Catalog entity ids that all match this fact's normalized value.
+     * Despite the historical name suggesting `$member`, these are general
+     * catalog entities (founders, companies, etc.) — the resolver picks
+     * which one the user intends to claim.
+     */
+    candidateEntityIds: import("@sinclair/typebox").TArray<import("@sinclair/typebox").TInteger>;
+    /** Total number of matching candidates; candidateEntityIds may be capped for UI payload size. */
+    candidateCount: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+    /**
+     * Which fact (events.id) raised the collision. Lets the resolver replay
+     * the binding once the human picks a winner.
+     */
+    triggeringEventId: import("@sinclair/typebox").TInteger;
+    /** Rule that would have fired if the match were unambiguous. */
+    relationshipTypeId: import("@sinclair/typebox").TOptional<import("@sinclair/typebox").TInteger>;
+}>;
+export type ClaimCollisionPayload = Static<typeof ClaimCollisionPayload>;
+export declare const IDENTITY_FACT_SEMANTIC_TYPE: "identity_fact";
+export declare const CLAIM_COLLISION_SEMANTIC_TYPE: "claim_collision";
+//# sourceMappingURL=identity-types.d.ts.map

package/dist/identity-types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"identity-types.d.ts","sourceRoot":"","sources":["../src/identity-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAQ,KAAK,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAMtD;;;;GAIG;AACH,eAAO,MAAM,cAAc,gRAQ1B,CAAC;AACF,MAAM,MAAM,cAAc,GAAG,MAAM,CAAC,OAAO,cAAc,CAAC,CAAC;AAS3D,wBAAgB,cAAc,CAAC,MAAM,EAAE,cAAc,EAAE,QAAQ,EAAE,cAAc,GAAG,OAAO,CAExF;AAMD,eAAO,MAAM,aAAa;IAEtB,gFAAgF;;IAEhF,6DAA6D;;IAE7D;;;OAGG;;IAEH,4CAA4C;;IAE5C;;;OAGG;;IAEH;;;OAGG;;IAEH,qFAAqF;;IAErF;;;OAGG;;EAIN,CAAC;AACF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAMzD;;;GAGG;AACH,eAAO,MAAM,2BAA2B;;;;;;;EAavC,CAAC;AACF,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAOrF;;;;;GAKG;AACH,eAAO,MAAM,aAAa,gJAGzB,CAAC;AACF,MAAM,MAAM,aAAa,GAAG,MAAM,CAAC,OAAO,aAAa,CAAC,CAAC;AAEzD,eAAO,MAAM,kBAAkB;IAE3B,gDAAgD;;IAEhD;;;OAGG;;IAEH;;;OAGG;;;IAGH;;OAEG;;EAIN,CAAC;AACF,MAAM,MAAM,kBAAkB,GAAG,MAAM,CAAC,OAAO,kBAAkB,CAAC,CAAC;AAEnE;;;;GAIG;AACH,eAAO,MAAM,gCAAgC;;QA3BzC,gDAAgD;;QAEhD;;;WAGG;;QAEH;;;WAGG;;;QAGH;;WAEG;;;IAeH,iGAAiG;;IAEjG,2EAA2E;;EAI9E,CAAC;AACF,MAAM,MAAM,gCAAgC,GAAG,MAAM,CAAC,OAAO,gCAAgC,CAAC,CAAC;AAO/F;;;;;;;GAOG;AACH,eAAO,MAAM,iBAAiB;;;;;;;IAQ1B,4FAA4F;;;EAK/F,CAAC;AACF,MAAM,MAAM,iBAAiB,GAAG,MAAM,CAAC,OAAO,iBAAiB,CAAC,CAAC;AAOjE,eAAO,MAAM,qBAAqB;IAE9B,2DAA2D;;IAE3D,yEAAyE;;IAEzE,2EAA2E;;IAE3E,oEAAoE;;IAEpE,0EAA0E;;IAE1E,8FAA8F;;EAIjG,CAAC;AACF,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAEzE;;;;GAIG;AACH,eAAO,MAAM,2BAA2B;;QAtBpC,2DAA2D;;QAE3D,yEAAyE;;QAEzE,2EAA2E;;QAE3E,oEAAoE;;QAEpE,0EAA0E;;QAE1E,8FAA8F;;;EAiBjG,CAAC;AACF,MAAM,MAAM,2BAA2B,GAAG,MAAM,CAAC,OAAO,2BAA2B,CAAC,CAAC;AAMrF;;;;;;GAMG;AACH,eAAO,MAAM,qBAAqB;;;;;IAM9B;;;;;OAKG;;IAKH,iGAAiG;;IAEjG;;;OAGG;;IAEH,gEAAgE;;EAInE,CAAC;AACF,MAAM,MAAM,qBAAqB,GAAG,MAAM,CAAC,OAAO,qBAAqB,CAAC,CAAC;AAOzE,eAAO,MAAM,2BAA2B,EAAG,eAAwB,CAAC;AACpE,eAAO,MAAM,6BAA6B,EAAG,iBAA0B,CAAC"}