contextkit-sdk 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,524 @@
+type FetchLike = (input: string, init: {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal: AbortSignal;
+}) => Promise<{
+    status: number;
+    headers: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}>;
+interface HttpOptions {
+    fetchImpl: FetchLike;
+    timeoutMs: number;
+    userAgent: string;
+}
+
+/**
+ * Wire types. These mirror the ContextKit API field-for-field: request
+ * parameters are snake_case on the wire (the SDK accepts camelCase and
+ * translates), response bodies are returned as the API sends them.
+ */
+declare const APP_SCOPES: readonly ["location.verify.zone", "location.place.current", "location.place.presence", "location.visits.read", "location.lookup.place", "location.rules.place", "location.rules.zone", "location.places.watch", "location.latest.read", "location.history.read", "location.lookup"];
+type AppScope = (typeof APP_SCOPES)[number];
+declare const SENSITIVE_SCOPES: readonly AppScope[];
+declare function isAppScope(value: string): value is AppScope;
+/** Limits the API enforces; the SDK checks them before sending. */
+declare const MIN_ZONE_RADIUS_M = 100;
+declare const MAX_ZONE_RADIUS_M = 10000;
+declare const MIN_MAX_AGE_S = 60;
+declare const MAX_MAX_AGE_S = 86400;
+declare const DEFAULT_MAX_AGE_S = 900;
+declare const MIN_DWELL_MINUTES = 5;
+declare const MAX_DWELL_MINUTES = 720;
+declare const MIN_EVENT_AGE_S = 30;
+declare const MAX_EVENT_AGE_S = 3600;
+/** Raw body of POST /v1/oauth/token. */
+interface TokenResponse {
+    access_token: string;
+    token_type: "Bearer";
+    expires_in: number;
+    refresh_token: string;
+    refresh_token_expires_at: string | null;
+    scope: string;
+    /** Pairwise per-app user id. Present once the API ships it; optional until then. */
+    sub?: string;
+}
+/** What the integrator persists per user. Refresh tokens ROTATE: every
+ *  refresh returns a new one and invalidates the old, so store what
+ *  `onTokens` hands you or the next refresh fails. */
+interface TokenSet {
+    accessToken: string;
+    /** Epoch milliseconds when `accessToken` stops working. */
+    accessTokenExpiresAt: number;
+    refreshToken: string;
+    /** ISO timestamp of the grant's horizon, or null for no expiry. */
+    refreshTokenExpiresAt: string | null;
+    scopes: AppScope[];
+    sub: string | null;
+}
+type UnknownReason = "stale" | "no_data" | "boundary";
+interface PlaceRef {
+    id: string;
+    label: string;
+    kind: string | null;
+}
+interface ZoneAnswer {
+    state: "inside" | "outside" | "unknown";
+    reason: UnknownReason | null;
+    asOf: string | null;
+    ageSeconds: number | null;
+}
+interface CurrentPlaceAnswer {
+    place: PlaceRef | null;
+    state: "at_place" | "no_place" | "unknown";
+    reason: UnknownReason | null;
+    asOf: string | null;
+    ageSeconds: number | null;
+}
+interface PresenceAnswer {
+    state: "yes" | "no" | "unknown";
+    reason: UnknownReason | null;
+    asOf: string | null;
+    ageSeconds: number | null;
+}
+interface SharedPlaceRef {
+    id: string;
+    label: string;
+    kind: string | null;
+}
+interface SharedPlaceList {
+    /** Bumps whenever the set of places shared with this app changes. */
+    version: number;
+    places: SharedPlaceRef[];
+}
+interface Visit {
+    arrival: string;
+    /** null while the visit is still open. */
+    departure: string | null;
+    place: PlaceRef;
+}
+interface VisitsPage {
+    visits: Visit[];
+    nextCursor: string | null;
+}
+interface PlaceLookup {
+    place: PlaceRef | null;
+    matched: boolean;
+    asOf: string | null;
+    deltaSeconds: number | null;
+}
+declare const LOCATION_SOURCES: readonly ["slc", "visit", "precise"];
+type LocationSource = (typeof LOCATION_SOURCES)[number];
+interface LocationPoint {
+    id: string;
+    /** When the fix was measured. ISO8601 UTC. */
+    timestamp: string;
+    lat: number;
+    lon: number;
+    horizontalAccuracy?: number;
+    altitude?: number;
+    speed?: number;
+    course?: number;
+    source: LocationSource;
+    visitArrival?: string;
+    visitDeparture?: string;
+    batteryLevel?: number;
+    deviceId?: string;
+}
+interface PointsPage {
+    points: LocationPoint[];
+    nextCursor?: string;
+}
+interface LatestPoint {
+    point: LocationPoint;
+    ageSeconds: number;
+}
+interface PointAt {
+    point: LocationPoint;
+    deltaSeconds: number;
+}
+interface DaysWithData {
+    /** "YYYY-MM-DD" in the requested timezone. */
+    days: string[];
+}
+type RuleType = "enter" | "exit" | "dwell";
+type RuleTarget = {
+    place_id: string;
+    label: string;
+} | {
+    lat: number;
+    lon: number;
+    radius_m: number;
+    label: string;
+};
+interface RuleSummary {
+    id: string;
+    type: RuleType;
+    target: RuleTarget;
+    dwell_minutes: number | null;
+    max_event_age_s: number | null;
+    webhook_url: string;
+    disabled_at: string | null;
+    created_at: string;
+}
+/** Returned once, at creation. Sign-verify every delivery with it. */
+type CreatedRule = RuleSummary & {
+    secret: string;
+};
+declare const CONNECTION_EVENTS: readonly ["places.changed"];
+type ConnectionEventName = (typeof CONNECTION_EVENTS)[number];
+interface SubscriptionSummary {
+    id: string;
+    events: string[];
+    webhook_url: string;
+    disabled_at: string | null;
+    created_at: string;
+}
+type CreatedSubscription = SubscriptionSummary & {
+    secret: string;
+};
+interface RuleWebhookEvent {
+    event_id: string;
+    rule_id: string;
+    grant_id: string;
+    /** "place.enter" | "place.exit" | "place.dwell" | "zone.enter" | ... */
+    type: string;
+    occurred_at: string;
+    target: {
+        place_id?: string;
+        label: string;
+    };
+}
+interface ConnectionWebhookEvent {
+    event_id: string;
+    subscription_id: string;
+    grant_id: string;
+    type: ConnectionEventName;
+    occurred_at: string;
+    places_version: number;
+}
+type WebhookEvent = RuleWebhookEvent | ConnectionWebhookEvent;
+declare function isRuleEvent(event: WebhookEvent): event is RuleWebhookEvent;
+declare function isConnectionEvent(event: WebhookEvent): event is ConnectionWebhookEvent;
+
+/** The minimum a caller must hold per user. A full TokenSet is accepted. */
+interface UserTokens {
+    refreshToken: string;
+    accessToken?: string;
+    /** Epoch ms. Without it the first call refreshes. */
+    accessTokenExpiresAt?: number;
+}
+interface UserClientOptions {
+    /**
+     * Called every time tokens change (after a refresh). PERSIST THEM: refresh
+     * tokens rotate, and the old one is dead the moment this fires. Awaited;
+     * a throw here fails the call that triggered the refresh.
+     */
+    onTokens?: (tokens: TokenSet) => void | Promise<void>;
+}
+interface VerifyZoneParams {
+    lat: number;
+    lon: number;
+    /** 100–10 000. Smaller zones are a triangulation tool, not a question. */
+    radiusM: number;
+    /** 3–80 chars; shown to the user in their access log. */
+    label: string;
+    /** How stale a fix may be and still count. 60–86 400, default 900. */
+    maxAgeS?: number;
+}
+interface VisitsListParams {
+    from?: string;
+    to?: string;
+    /** 1–500 */
+    limit?: number;
+    cursor?: string;
+}
+interface RangeParams {
+    from: string;
+    to: string;
+    deviceId?: string;
+    source?: LocationSource;
+    /** 1–5000 */
+    limit?: number;
+    cursor?: string;
+}
+interface BaseRuleParams {
+    type: RuleType;
+    /** 5–720; only for `dwell`. */
+    dwellMinutes?: number;
+    /** 30–3600; deliveries older than this are abandoned, not retried. */
+    maxEventAgeS?: number;
+    /** https only. */
+    webhookUrl: string;
+}
+interface CreatePlaceRuleParams extends BaseRuleParams {
+    placeId: string;
+}
+interface CreateZoneRuleParams extends BaseRuleParams {
+    lat: number;
+    lon: number;
+    radiusM: number;
+    label: string;
+}
+/**
+ * All calls for one connected user. Handles access-token refresh: refreshes
+ * before expiry, retries once on 401, and raises TokenRevokedError when a
+ * refresh fails — at which point the user must reconnect.
+ */
+declare class UserClient {
+    private readonly http;
+    private readonly apiBaseUrl;
+    private readonly refreshImpl;
+    private readonly options;
+    private tokens;
+    private refreshing;
+    constructor(http: HttpOptions, apiBaseUrl: string, refreshImpl: (refreshToken: string) => Promise<TokenSet>, tokens: UserTokens, options: UserClientOptions);
+    /** The tokens this client currently holds. */
+    currentTokens(): Readonly<UserTokens>;
+    readonly answers: {
+        /** Is the user inside this circle right now? "unknown" is a value. */
+        verifyZone: (params: VerifyZoneParams) => Promise<ZoneAnswer>;
+        /** Which of the places shared with this app is the user at, if any? */
+        currentPlace: (params?: {
+            maxAgeS?: number;
+        }) => Promise<CurrentPlaceAnswer>;
+        /** The places the user chose to share with this app. Cache by `version`. */
+        places: () => Promise<SharedPlaceList>;
+        /** Is the user at this shared place right now? */
+        presence: (placeId: string, params?: {
+            maxAgeS?: number;
+        }) => Promise<PresenceAnswer>;
+    };
+    readonly visits: {
+        /** Stays at shared places, newest first. Follow `nextCursor`. */
+        list: (params?: VisitsListParams) => Promise<VisitsPage>;
+        /** Which shared place was the user at, at this instant? */
+        lookupPlace: (params: {
+            at: string;
+            toleranceS?: number;
+        }) => Promise<PlaceLookup>;
+    };
+    /** Sensitive tier: raw coordinates. Needs the location.*.read / lookup scopes. */
+    readonly locations: {
+        range: (params: RangeParams) => Promise<PointsPage>;
+        /** Which calendar days (in `tz`) have any points. */
+        days: (params: {
+            from: string;
+            to: string;
+            tz: string;
+        }) => Promise<DaysWithData>;
+        latest: () => Promise<LatestPoint>;
+        /** The point nearest `at`, within `toleranceS`. 404 if none. */
+        at: (params: {
+            at: string;
+            toleranceS?: number;
+            source?: LocationSource;
+        }) => Promise<PointAt>;
+    };
+    readonly rules: {
+        /** Fire a webhook when the user enters / exits / dwells at a shared place.
+         *  The returned `secret` is shown once; keep it to verify deliveries. */
+        createPlace: (params: CreatePlaceRuleParams) => Promise<CreatedRule>;
+        createZone: (params: CreateZoneRuleParams) => Promise<CreatedRule>;
+        /** Every rule this app holds for the user, place and zone alike. */
+        list: () => Promise<RuleSummary[]>;
+        deletePlace: (ruleId: string) => Promise<void>;
+        deleteZone: (ruleId: string) => Promise<void>;
+    };
+    readonly subscriptions: {
+        /** One subscription per grant; registering again replaces it and mints a
+         *  new secret. */
+        register: (params: {
+            events: readonly ConnectionEventName[];
+            webhookUrl: string;
+        }) => Promise<CreatedSubscription>;
+        get: () => Promise<SubscriptionSummary | null>;
+        remove: (subscriptionId: string) => Promise<void>;
+    };
+    private call;
+    private send;
+    private accessToken;
+    /** Single-flight: concurrent calls share one refresh, because the second
+     *  use of a rotated refresh token is treated as replay and kills the grant. */
+    private refresh;
+}
+
+declare const DEFAULT_API_BASE_URL = "https://api.contextkit.com";
+declare const DEFAULT_AUTHORIZE_BASE_URL = "https://contextkit.com";
+declare const DEFAULT_TIMEOUT_MS = 10000;
+interface ContextKitOptions {
+    /** The app's client id (a UUID) from the developer portal. */
+    clientId: string;
+    /** The app's client secret. Server-side only — never ship this to a browser. */
+    clientSecret: string;
+    /** Defaults to https://api.contextkit.com */
+    apiBaseUrl?: string;
+    /** Where users are sent to consent. Defaults to https://contextkit.com */
+    authorizeBaseUrl?: string;
+    /** Per-request timeout. Defaults to 10s. */
+    timeoutMs?: number;
+    /** Injectable for tests; defaults to global fetch (Node 20+). */
+    fetch?: FetchLike;
+}
+interface AuthorizeUrlParams {
+    /** Must be one of the redirect URIs registered for the app. */
+    redirectUri: string;
+    scopes: readonly AppScope[];
+    /** Opaque, unguessable, bound to the user's session. Echoed back on the
+     *  redirect; refuse the callback if it does not match. */
+    state: string;
+    /** Keep the verifier in the user's session; the challenge is derived here. */
+    codeVerifier: string;
+    /** Your own id for this user. Stored on the grant and shown to you in the
+     *  portal's Users tab. Optional; never shown to the user. */
+    externalUserId?: string;
+}
+interface ExchangeCodeParams {
+    code: string;
+    codeVerifier: string;
+    redirectUri: string;
+}
+/**
+ * One instance per app. Holds the client credentials and builds per-user
+ * handles with `forUser`.
+ */
+declare class ContextKit {
+    readonly clientId: string;
+    readonly apiBaseUrl: string;
+    readonly authorizeBaseUrl: string;
+    private readonly clientSecret;
+    private readonly http;
+    constructor(options: ContextKitOptions);
+    /** The URL to send the user to. */
+    authorizeUrl(params: AuthorizeUrlParams): string;
+    /** Callback step: trade the code for tokens. Persist the result per user. */
+    exchangeCode(params: ExchangeCodeParams): Promise<TokenSet>;
+    /**
+     * Refresh explicitly. `forUser` does this for you; call it directly only
+     * for a scheduled refresh. Refresh tokens rotate — persist the new set.
+     */
+    refresh(refreshToken: string): Promise<TokenSet>;
+    /** A handle that makes calls as one connected user. */
+    forUser(tokens: UserTokens, options?: UserClientOptions): UserClient;
+    private token;
+}
+
+/** 43-character base64url verifier (32 random bytes), the RFC 7636 minimum. */
+declare function generateCodeVerifier(): string;
+/** S256 challenge for a verifier — the only method the API accepts. */
+declare function codeChallenge(verifier: string): string;
+/** 32 random bytes as base64url; use as the OAuth `state`. */
+declare function generateState(): string;
+
+/**
+ * ContextKit signs every delivery Stripe-style:
+ *   X-ContextKit-Signature: t=<unix seconds>,v1=<hex hmac-sha256(secret, `${t}.${body}`)>
+ * Retries are re-signed, so a receiver never needs a window wider than
+ * realistic clock skew. This must agree byte-for-byte with the API's
+ * webhook-delivery.service.ts and the Explorer relay's signature.ts.
+ */
+declare const RECOMMENDED_TOLERANCE_S = 60;
+declare const MAX_TOLERANCE_S = 300;
+declare const SIGNATURE_HEADER = "x-contextkit-signature";
+/** Something that remembers event ids it has already accepted. Needed for
+ *  replay protection across your own retries or a duplicated delivery. */
+interface ReplayGuard {
+    /** Return true if this id was already seen; otherwise record it. */
+    seen(eventId: string, occurredAtMs: number): boolean | Promise<boolean>;
+}
+interface VerifyWebhookParams {
+    /** The EXACT bytes received. Re-serialising a parsed body breaks the HMAC. */
+    rawBody: Buffer | string;
+    /** The X-ContextKit-Signature header value. */
+    signature: string | string[] | undefined;
+    /** The secret returned when the rule or subscription was created. */
+    secret: string;
+    /** Seconds of clock skew to allow. Default 60, max 300. */
+    toleranceS?: number;
+    replayGuard?: ReplayGuard;
+    /** Injectable clock, epoch ms. */
+    now?: number;
+}
+/**
+ * Verify a delivery and return its parsed event. Throws
+ * WebhookVerificationError on any failure — respond 400 and do NOT act.
+ */
+declare function verifyWebhook(params: VerifyWebhookParams): Promise<WebhookEvent>;
+/** Build the header for a body — for tests and for simulating deliveries. */
+declare function signWebhook(body: Buffer | string, secret: string, atMs?: number): string;
+declare function parseSignatureHeader(header: string): {
+    timestamp: number;
+    signatures: string[];
+} | null;
+/**
+ * A process-local replay guard. Fine for a single instance; behind more than
+ * one replica, back `ReplayGuard` with something shared (Redis SET NX EX).
+ */
+declare class InMemoryReplayGuard implements ReplayGuard {
+    private readonly ttlMs;
+    private readonly ids;
+    constructor(ttlMs?: number);
+    seen(eventId: string, _occurredAtMs: number): boolean;
+}
+
+/**
+ * Every failure the SDK raises is a ContextKitError. Subclasses tell the
+ * caller what to DO, which is the only reason to distinguish them:
+ *
+ *   TokenRevokedError   → the user must reconnect; stop retrying
+ *   RateLimitedError    → wait `retryAfterSeconds`, then retry
+ *   TimeoutError / NetworkError → transient; retry with backoff
+ *   ValidationError / ScopeError / NotFoundError → caller bug or stale id; do not retry
+ *
+ * "unknown" answers are NOT errors. They come back as values.
+ */
+declare class ContextKitError extends Error {
+    readonly code: string;
+    readonly status: number | null;
+    readonly body: unknown;
+    constructor(message: string, code: string, status?: number | null, body?: unknown);
+}
+/** 400 — the request shape was wrong. `messages` is what the API said. */
+declare class ValidationError extends ContextKitError {
+    readonly messages: string[];
+    constructor(messages: string[], body: unknown);
+}
+/** 401 that a refresh could not fix, or a refresh that itself failed. The
+ *  grant is gone (revoked, expired, app deactivated, or the refresh token
+ *  was replayed). Send the user back through the connect flow. */
+declare class TokenRevokedError extends ContextKitError {
+    constructor(message?: string, body?: unknown);
+}
+/** 403 — the grant does not carry the scope this call needs. */
+declare class ScopeError extends ContextKitError {
+    constructor(message: string, body: unknown);
+}
+/** 404 — unshared and nonexistent are deliberately the same answer. */
+declare class NotFoundError extends ContextKitError {
+    constructor(message: string, body: unknown);
+}
+/** 429 — per-app budget or rate limit. Honour `retryAfterSeconds`. */
+declare class RateLimitedError extends ContextKitError {
+    readonly retryAfterSeconds: number | null;
+    constructor(message: string, retryAfterSeconds: number | null, body: unknown);
+}
+/** Any other non-2xx. */
+declare class ApiError extends ContextKitError {
+    constructor(message: string, status: number, body: unknown);
+}
+declare class TimeoutError extends ContextKitError {
+    constructor(url: string, timeoutMs: number);
+}
+declare class NetworkError extends ContextKitError {
+    readonly cause: unknown;
+    constructor(url: string, cause: unknown);
+}
+/** A webhook delivery that failed signature or freshness checks. */
+declare class WebhookVerificationError extends ContextKitError {
+    constructor(detail: string);
+}
+
+export { APP_SCOPES, ApiError, type AppScope, type AuthorizeUrlParams, CONNECTION_EVENTS, type ConnectionEventName, type ConnectionWebhookEvent, ContextKit, ContextKitError, type ContextKitOptions, type CreatePlaceRuleParams, type CreateZoneRuleParams, type CreatedRule, type CreatedSubscription, type CurrentPlaceAnswer, DEFAULT_API_BASE_URL, DEFAULT_AUTHORIZE_BASE_URL, DEFAULT_MAX_AGE_S, DEFAULT_TIMEOUT_MS, type DaysWithData, type ExchangeCodeParams, InMemoryReplayGuard, LOCATION_SOURCES, type LatestPoint, type LocationPoint, type LocationSource, MAX_DWELL_MINUTES, MAX_EVENT_AGE_S, MAX_MAX_AGE_S, MAX_TOLERANCE_S, MAX_ZONE_RADIUS_M, MIN_DWELL_MINUTES, MIN_EVENT_AGE_S, MIN_MAX_AGE_S, MIN_ZONE_RADIUS_M, NetworkError, NotFoundError, type PlaceLookup, type PlaceRef, type PointAt, type PointsPage, type PresenceAnswer, RECOMMENDED_TOLERANCE_S, type RangeParams, RateLimitedError, type ReplayGuard, type RuleSummary, type RuleTarget, type RuleType, type RuleWebhookEvent, SENSITIVE_SCOPES, SIGNATURE_HEADER, ScopeError, type SharedPlaceList, type SharedPlaceRef, type SubscriptionSummary, TimeoutError, type TokenResponse, TokenRevokedError, type TokenSet, type UnknownReason, UserClient, type UserClientOptions, type UserTokens, ValidationError, type VerifyWebhookParams, type VerifyZoneParams, type Visit, type VisitsListParams, type VisitsPage, type WebhookEvent, WebhookVerificationError, type ZoneAnswer, codeChallenge, generateCodeVerifier, generateState, isAppScope, isConnectionEvent, isRuleEvent, parseSignatureHeader, signWebhook, verifyWebhook };