contextkit-sdk 0.1.0

package/dist/index.js

@@ -0,0 +1,604 @@
+import { randomBytes, createHash, createHmac, timingSafeEqual } from 'crypto';
+
+// src/errors.ts
+var ContextKitError = class extends Error {
+  code;
+  status;
+  body;
+  constructor(message, code, status = null, body = null) {
+    super(message);
+    this.name = new.target.name;
+    this.code = code;
+    this.status = status;
+    this.body = body;
+  }
+};
+var ValidationError = class extends ContextKitError {
+  messages;
+  constructor(messages, body) {
+    super(messages.join("; ") || "validation failed", "validation", 400, body);
+    this.messages = messages;
+  }
+};
+var TokenRevokedError = class extends ContextKitError {
+  constructor(message = "grant is no longer valid; the user must reconnect", body = null) {
+    super(message, "token_revoked", 401, body);
+  }
+};
+var ScopeError = class extends ContextKitError {
+  constructor(message, body) {
+    super(message, "scope", 403, body);
+  }
+};
+var NotFoundError = class extends ContextKitError {
+  constructor(message, body) {
+    super(message, "not_found", 404, body);
+  }
+};
+var RateLimitedError = class extends ContextKitError {
+  retryAfterSeconds;
+  constructor(message, retryAfterSeconds, body) {
+    super(message, "rate_limited", 429, body);
+    this.retryAfterSeconds = retryAfterSeconds;
+  }
+};
+var ApiError = class extends ContextKitError {
+  constructor(message, status, body) {
+    super(message, "api", status, body);
+  }
+};
+var TimeoutError = class extends ContextKitError {
+  constructor(url, timeoutMs) {
+    super(`request to ${url} timed out after ${timeoutMs}ms`, "timeout");
+  }
+};
+var NetworkError = class extends ContextKitError {
+  cause;
+  constructor(url, cause) {
+    super(`request to ${url} failed: ${describe(cause)}`, "network");
+    this.cause = cause;
+  }
+};
+var WebhookVerificationError = class extends ContextKitError {
+  constructor(detail) {
+    super(detail, "webhook_verification");
+  }
+};
+function describe(err) {
+  return err instanceof Error ? err.message : String(err);
+}
+
+// src/http.ts
+var UnauthorizedSignal = class extends Error {
+  body;
+  constructor(body) {
+    super("unauthorized");
+    this.body = body;
+  }
+};
+async function request(opts, req) {
+  const url = withQuery(req.url, req.query);
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), opts.timeoutMs);
+  let status;
+  let text;
+  let headers;
+  try {
+    const res = await opts.fetchImpl(url, {
+      method: req.method,
+      headers: {
+        "accept": "application/json",
+        "user-agent": opts.userAgent,
+        ...req.body !== void 0 ? { "content-type": "application/json" } : {},
+        ...req.headers ?? {}
+      },
+      ...req.body !== void 0 ? { body: JSON.stringify(req.body) } : {},
+      signal: controller.signal
+    });
+    status = res.status;
+    headers = res.headers;
+    text = await res.text();
+  } catch (err) {
+    if (controller.signal.aborted) throw new TimeoutError(url, opts.timeoutMs);
+    throw new NetworkError(url, err);
+  } finally {
+    clearTimeout(timer);
+  }
+  const data = parseJson(text);
+  if (status >= 200 && status < 300) return { status, data, headers };
+  const message = errorMessage(data, status);
+  switch (status) {
+    case 400:
+      throw new ValidationError(errorMessages(data), data);
+    case 401:
+      throw new UnauthorizedSignal(data);
+    case 403:
+      throw new ScopeError(message, data);
+    case 404:
+      throw new NotFoundError(message, data);
+    case 429:
+      throw new RateLimitedError(message, retryAfter(headers.get("retry-after")), data);
+    default:
+      throw new ApiError(message, status, data);
+  }
+}
+function withQuery(url, query) {
+  if (!query) return url;
+  const params = new URLSearchParams();
+  for (const [key, value] of Object.entries(query)) {
+    if (value !== void 0) params.set(key, String(value));
+  }
+  const qs = params.toString();
+  return qs ? `${url}?${qs}` : url;
+}
+function parseJson(text) {
+  if (!text) return null;
+  try {
+    return JSON.parse(text);
+  } catch {
+    return text;
+  }
+}
+function errorMessages(data) {
+  if (data && typeof data === "object" && "message" in data) {
+    const m = data.message;
+    if (Array.isArray(m)) return m.map(String);
+    if (typeof m === "string") return [m];
+  }
+  return [];
+}
+function errorMessage(data, status) {
+  const messages = errorMessages(data);
+  return messages.length ? messages.join("; ") : `HTTP ${status}`;
+}
+function retryAfter(header) {
+  if (!header) return null;
+  const n = Number(header);
+  return Number.isFinite(n) && n >= 0 ? n : null;
+}
+function generateCodeVerifier() {
+  return base64url(randomBytes(32));
+}
+function codeChallenge(verifier) {
+  return base64url(createHash("sha256").update(verifier, "utf8").digest());
+}
+function generateState() {
+  return base64url(randomBytes(32));
+}
+function base64url(buf) {
+  return buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+}
+
+// src/types.ts
+var APP_SCOPES = [
+  // standard — answers, not data
+  "location.verify.zone",
+  "location.place.current",
+  "location.place.presence",
+  "location.visits.read",
+  "location.lookup.place",
+  "location.rules.place",
+  "location.rules.zone",
+  "location.places.watch",
+  // sensitive — raw coordinates
+  "location.latest.read",
+  "location.history.read",
+  "location.lookup"
+];
+var SENSITIVE_SCOPES = [
+  "location.latest.read",
+  "location.history.read",
+  "location.lookup"
+];
+function isAppScope(value) {
+  return APP_SCOPES.includes(value);
+}
+var MIN_ZONE_RADIUS_M = 100;
+var MAX_ZONE_RADIUS_M = 1e4;
+var MIN_MAX_AGE_S = 60;
+var MAX_MAX_AGE_S = 86400;
+var DEFAULT_MAX_AGE_S = 900;
+var MIN_DWELL_MINUTES = 5;
+var MAX_DWELL_MINUTES = 720;
+var MIN_EVENT_AGE_S = 30;
+var MAX_EVENT_AGE_S = 3600;
+var LOCATION_SOURCES = ["slc", "visit", "precise"];
+var CONNECTION_EVENTS = ["places.changed"];
+function isRuleEvent(event) {
+  return "rule_id" in event;
+}
+function isConnectionEvent(event) {
+  return "subscription_id" in event;
+}
+
+// src/user.ts
+var EXPIRY_SKEW_MS = 3e4;
+var UserClient = class {
+  constructor(http, apiBaseUrl, refreshImpl, tokens, options) {
+    this.http = http;
+    this.apiBaseUrl = apiBaseUrl;
+    this.refreshImpl = refreshImpl;
+    this.options = options;
+    if (!tokens.refreshToken) throw new Error("forUser: refreshToken is required");
+    this.tokens = { ...tokens };
+  }
+  http;
+  apiBaseUrl;
+  refreshImpl;
+  options;
+  tokens;
+  refreshing = null;
+  /** The tokens this client currently holds. */
+  currentTokens() {
+    return this.tokens;
+  }
+  answers = {
+    /** Is the user inside this circle right now? "unknown" is a value. */
+    verifyZone: async (params) => {
+      assertRange("radiusM", params.radiusM, MIN_ZONE_RADIUS_M, MAX_ZONE_RADIUS_M);
+      if (params.maxAgeS !== void 0)
+        assertRange("maxAgeS", params.maxAgeS, MIN_MAX_AGE_S, MAX_MAX_AGE_S);
+      return this.call({
+        method: "POST",
+        url: "/v1/answers/verify-zone",
+        body: {
+          lat: params.lat,
+          lon: params.lon,
+          radius_m: params.radiusM,
+          label: params.label,
+          ...params.maxAgeS !== void 0 ? { max_age_s: params.maxAgeS } : {}
+        }
+      });
+    },
+    /** Which of the places shared with this app is the user at, if any? */
+    currentPlace: (params = {}) => this.call({
+      method: "GET",
+      url: "/v1/answers/current-place",
+      query: { max_age_s: params.maxAgeS }
+    }),
+    /** The places the user chose to share with this app. Cache by `version`. */
+    places: () => this.call({ method: "GET", url: "/v1/answers/places" }),
+    /** Is the user at this shared place right now? */
+    presence: (placeId, params = {}) => this.call({
+      method: "GET",
+      url: `/v1/answers/places/${encodeURIComponent(placeId)}/presence`,
+      query: { max_age_s: params.maxAgeS }
+    })
+  };
+  visits = {
+    /** Stays at shared places, newest first. Follow `nextCursor`. */
+    list: (params = {}) => this.call({
+      method: "GET",
+      url: "/v1/visits",
+      query: { from: params.from, to: params.to, limit: params.limit, cursor: params.cursor }
+    }),
+    /** Which shared place was the user at, at this instant? */
+    lookupPlace: (params) => this.call({
+      method: "GET",
+      url: "/v1/lookup/place",
+      query: { at: params.at, tolerance_s: params.toleranceS }
+    })
+  };
+  /** Sensitive tier: raw coordinates. Needs the location.*.read / lookup scopes. */
+  locations = {
+    range: (params) => this.call({
+      method: "GET",
+      url: "/v1/locations/timerange",
+      query: {
+        from: params.from,
+        to: params.to,
+        device_id: params.deviceId,
+        source: params.source,
+        limit: params.limit,
+        cursor: params.cursor
+      }
+    }),
+    /** Which calendar days (in `tz`) have any points. */
+    days: (params) => this.call({
+      method: "GET",
+      url: "/v1/locations/days",
+      query: { from: params.from, to: params.to, tz: params.tz }
+    }),
+    latest: () => this.call({ method: "GET", url: "/v1/locations/latest" }),
+    /** The point nearest `at`, within `toleranceS`. 404 if none. */
+    at: (params) => this.call({
+      method: "GET",
+      url: "/v1/locations/lookup",
+      query: { at: params.at, tolerance_s: params.toleranceS, source: params.source }
+    })
+  };
+  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) => this.call({
+      method: "POST",
+      url: "/v1/rules/place",
+      body: { place_id: params.placeId, ...ruleBody(params) }
+    }),
+    createZone: async (params) => {
+      assertRange("radiusM", params.radiusM, MIN_ZONE_RADIUS_M, MAX_ZONE_RADIUS_M);
+      return this.call({
+        method: "POST",
+        url: "/v1/rules/zone",
+        body: {
+          lat: params.lat,
+          lon: params.lon,
+          radius_m: params.radiusM,
+          label: params.label,
+          ...ruleBody(params)
+        }
+      });
+    },
+    /** Every rule this app holds for the user, place and zone alike. */
+    list: () => this.call({ method: "GET", url: "/v1/rules/place" }),
+    deletePlace: (ruleId) => this.call({ method: "DELETE", url: `/v1/rules/place/${encodeURIComponent(ruleId)}` }),
+    deleteZone: (ruleId) => this.call({ method: "DELETE", url: `/v1/rules/zone/${encodeURIComponent(ruleId)}` })
+  };
+  subscriptions = {
+    /** One subscription per grant; registering again replaces it and mints a
+     *  new secret. */
+    register: (params) => this.call({
+      method: "POST",
+      url: "/v1/subscriptions",
+      body: { events: [...params.events], webhook_url: params.webhookUrl }
+    }),
+    get: () => this.call({ method: "GET", url: "/v1/subscriptions" }),
+    remove: (subscriptionId) => this.call({
+      method: "DELETE",
+      url: `/v1/subscriptions/${encodeURIComponent(subscriptionId)}`
+    })
+  };
+  // -------------------------------------------------------------------------
+  async call(req) {
+    let accessToken = await this.accessToken();
+    try {
+      return await this.send(req, accessToken);
+    } catch (err) {
+      if (!(err instanceof UnauthorizedSignal)) throw err;
+    }
+    accessToken = (await this.refresh()).accessToken;
+    try {
+      return await this.send(req, accessToken);
+    } catch (err) {
+      if (err instanceof UnauthorizedSignal) throw new TokenRevokedError(void 0, err.body);
+      throw err;
+    }
+  }
+  async send(req, accessToken) {
+    const res = await request(this.http, {
+      ...req,
+      url: `${this.apiBaseUrl}${req.url}`,
+      headers: { authorization: `Bearer ${accessToken}` }
+    });
+    return res.data;
+  }
+  async accessToken() {
+    const { accessToken, accessTokenExpiresAt } = this.tokens;
+    if (accessToken && accessTokenExpiresAt && accessTokenExpiresAt - EXPIRY_SKEW_MS > Date.now()) {
+      return accessToken;
+    }
+    return (await this.refresh()).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. */
+  refresh() {
+    if (!this.refreshing) {
+      this.refreshing = this.refreshImpl(this.tokens.refreshToken).then(async (next) => {
+        this.tokens = {
+          refreshToken: next.refreshToken,
+          accessToken: next.accessToken,
+          accessTokenExpiresAt: next.accessTokenExpiresAt
+        };
+        if (this.options.onTokens) await this.options.onTokens(next);
+        return next;
+      }).finally(() => {
+        this.refreshing = null;
+      });
+    }
+    return this.refreshing;
+  }
+};
+function ruleBody(params) {
+  return {
+    type: params.type,
+    webhook_url: params.webhookUrl,
+    ...params.dwellMinutes !== void 0 ? { dwell_minutes: params.dwellMinutes } : {},
+    ...params.maxEventAgeS !== void 0 ? { max_event_age_s: params.maxEventAgeS } : {}
+  };
+}
+function assertRange(name, value, min, max) {
+  if (!Number.isInteger(value) || value < min || value > max) {
+    throw new RangeError(`${name} must be an integer between ${min} and ${max}, got ${value}`);
+  }
+}
+
+// src/client.ts
+var DEFAULT_API_BASE_URL = "https://api.contextkit.com";
+var DEFAULT_AUTHORIZE_BASE_URL = "https://contextkit.com";
+var DEFAULT_TIMEOUT_MS = 1e4;
+var VERSION = "0.1.0" ;
+var ContextKit = class {
+  clientId;
+  apiBaseUrl;
+  authorizeBaseUrl;
+  clientSecret;
+  http;
+  constructor(options) {
+    if (!options.clientId) throw new Error("ContextKit: clientId is required");
+    if (!options.clientSecret) throw new Error("ContextKit: clientSecret is required");
+    this.clientId = options.clientId;
+    this.clientSecret = options.clientSecret;
+    this.apiBaseUrl = stripSlash(options.apiBaseUrl ?? DEFAULT_API_BASE_URL);
+    this.authorizeBaseUrl = stripSlash(options.authorizeBaseUrl ?? DEFAULT_AUTHORIZE_BASE_URL);
+    const fetchImpl = options.fetch ?? globalThis.fetch;
+    if (!fetchImpl) throw new Error("ContextKit: no fetch available; pass options.fetch");
+    this.http = {
+      fetchImpl,
+      timeoutMs: options.timeoutMs ?? DEFAULT_TIMEOUT_MS,
+      userAgent: `contextkit-sdk/${VERSION} node/${process.versions.node}`
+    };
+  }
+  /** The URL to send the user to. */
+  authorizeUrl(params) {
+    if (params.scopes.length === 0) throw new Error("authorizeUrl: at least one scope is required");
+    for (const scope of params.scopes) {
+      if (!isAppScope(scope)) throw new Error(`authorizeUrl: unknown scope "${String(scope)}"`);
+    }
+    if (!params.state) throw new Error("authorizeUrl: state is required");
+    if (params.codeVerifier.length < 43 || params.codeVerifier.length > 128) {
+      throw new Error(
+        "authorizeUrl: codeVerifier must be 43\u2013128 characters (see generateCodeVerifier)"
+      );
+    }
+    const url = new URL(`${this.authorizeBaseUrl}/authorize`);
+    url.searchParams.set("client_id", this.clientId);
+    url.searchParams.set("redirect_uri", params.redirectUri);
+    url.searchParams.set("scope", params.scopes.join(" "));
+    url.searchParams.set("code_challenge", codeChallenge(params.codeVerifier));
+    url.searchParams.set("code_challenge_method", "S256");
+    url.searchParams.set("state", params.state);
+    if (params.externalUserId) url.searchParams.set("external_user_id", params.externalUserId);
+    return url.toString();
+  }
+  /** Callback step: trade the code for tokens. Persist the result per user. */
+  async exchangeCode(params) {
+    return this.token({
+      grantType: "authorization_code",
+      code: params.code,
+      codeVerifier: params.codeVerifier,
+      redirectUri: params.redirectUri
+    });
+  }
+  /**
+   * Refresh explicitly. `forUser` does this for you; call it directly only
+   * for a scheduled refresh. Refresh tokens rotate — persist the new set.
+   */
+  async refresh(refreshToken) {
+    return this.token({ grantType: "refresh_token", refreshToken });
+  }
+  /** A handle that makes calls as one connected user. */
+  forUser(tokens, options = {}) {
+    return new UserClient(this.http, this.apiBaseUrl, (rt) => this.refresh(rt), tokens, options);
+  }
+  async token(body) {
+    let res;
+    try {
+      res = await request(this.http, {
+        method: "POST",
+        url: `${this.apiBaseUrl}/v1/oauth/token`,
+        body: { clientId: this.clientId, clientSecret: this.clientSecret, ...body }
+      });
+    } catch (err) {
+      if (err instanceof UnauthorizedSignal) throw new TokenRevokedError(void 0, err.body);
+      if (err instanceof ValidationError && body.grantType === "refresh_token") {
+        throw new TokenRevokedError(err.message, err.body);
+      }
+      throw err;
+    }
+    return toTokenSet(res.data);
+  }
+};
+function toTokenSet(raw, now = Date.now()) {
+  return {
+    accessToken: raw.access_token,
+    accessTokenExpiresAt: now + raw.expires_in * 1e3,
+    refreshToken: raw.refresh_token,
+    refreshTokenExpiresAt: raw.refresh_token_expires_at ?? null,
+    scopes: raw.scope.split(" ").filter(isAppScope),
+    sub: raw.sub ?? null
+  };
+}
+function stripSlash(url) {
+  return url.replace(/\/+$/, "");
+}
+var RECOMMENDED_TOLERANCE_S = 60;
+var MAX_TOLERANCE_S = 300;
+var SIGNATURE_HEADER = "x-contextkit-signature";
+async function verifyWebhook(params) {
+  const header = Array.isArray(params.signature) ? params.signature[0] : params.signature;
+  if (!header) throw new WebhookVerificationError(`missing ${SIGNATURE_HEADER} header`);
+  const parsed = parseSignatureHeader(header);
+  if (!parsed) throw new WebhookVerificationError("malformed signature header");
+  const toleranceS = Math.min(params.toleranceS ?? RECOMMENDED_TOLERANCE_S, MAX_TOLERANCE_S);
+  const nowS = Math.floor((params.now ?? Date.now()) / 1e3);
+  const skew = nowS - parsed.timestamp;
+  if (Math.abs(skew) > toleranceS) {
+    throw new WebhookVerificationError(`timestamp ${skew}s outside ${toleranceS}s tolerance`);
+  }
+  const body = Buffer.isBuffer(params.rawBody) ? params.rawBody : Buffer.from(params.rawBody, "utf8");
+  const expected = signPayload(body, parsed.timestamp, params.secret);
+  if (!parsed.signatures.some((candidate) => constantTimeEquals(candidate, expected))) {
+    throw new WebhookVerificationError("no v1 signature matched \u2014 wrong secret or tampered body");
+  }
+  const event = parseEvent(body);
+  if (params.replayGuard) {
+    const occurredAtMs = Date.parse(event.occurred_at);
+    if (await params.replayGuard.seen(event.event_id, occurredAtMs)) {
+      throw new WebhookVerificationError(`event ${event.event_id} already processed`);
+    }
+  }
+  return event;
+}
+function signWebhook(body, secret, atMs = Date.now()) {
+  const t = Math.floor(atMs / 1e3);
+  const buf = Buffer.isBuffer(body) ? body : Buffer.from(body, "utf8");
+  return `t=${t},v1=${signPayload(buf, t, secret)}`;
+}
+function parseSignatureHeader(header) {
+  let timestamp = null;
+  const signatures = [];
+  for (const part of header.split(",")) {
+    const eq = part.indexOf("=");
+    if (eq === -1) return null;
+    const key = part.slice(0, eq).trim();
+    const value = part.slice(eq + 1).trim();
+    if (key === "t") {
+      const n = Number(value);
+      if (!Number.isFinite(n)) return null;
+      timestamp = n;
+    } else if (key === "v1") {
+      signatures.push(value.toLowerCase());
+    }
+  }
+  if (timestamp === null || signatures.length === 0) return null;
+  return { timestamp, signatures };
+}
+var InMemoryReplayGuard = class {
+  constructor(ttlMs = 10 * 6e4) {
+    this.ttlMs = ttlMs;
+  }
+  ttlMs;
+  ids = /* @__PURE__ */ new Map();
+  seen(eventId, _occurredAtMs) {
+    const now = Date.now();
+    for (const [id, at] of this.ids) if (now - at > this.ttlMs) this.ids.delete(id);
+    if (this.ids.has(eventId)) return true;
+    this.ids.set(eventId, now);
+    return false;
+  }
+};
+function signPayload(body, timestamp, secret) {
+  return createHmac("sha256", secret).update(Buffer.concat([Buffer.from(`${timestamp}.`, "utf8"), body])).digest("hex");
+}
+function parseEvent(body) {
+  let data;
+  try {
+    data = JSON.parse(body.toString("utf8"));
+  } catch {
+    throw new WebhookVerificationError("body is not JSON");
+  }
+  if (!data || typeof data !== "object" || typeof data.event_id !== "string" || typeof data.occurred_at !== "string" || typeof data.type !== "string") {
+    throw new WebhookVerificationError("body is not a ContextKit event");
+  }
+  return data;
+}
+function constantTimeEquals(a, b) {
+  const left = Buffer.from(a, "utf8");
+  const right = Buffer.from(b, "utf8");
+  if (left.length !== right.length) return false;
+  return timingSafeEqual(left, right);
+}
+
+export { APP_SCOPES, ApiError, CONNECTION_EVENTS, ContextKit, ContextKitError, DEFAULT_API_BASE_URL, DEFAULT_AUTHORIZE_BASE_URL, DEFAULT_MAX_AGE_S, DEFAULT_TIMEOUT_MS, InMemoryReplayGuard, LOCATION_SOURCES, 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, RECOMMENDED_TOLERANCE_S, RateLimitedError, SENSITIVE_SCOPES, SIGNATURE_HEADER, ScopeError, TimeoutError, TokenRevokedError, UserClient, ValidationError, WebhookVerificationError, codeChallenge, generateCodeVerifier, generateState, isAppScope, isConnectionEvent, isRuleEvent, parseSignatureHeader, signWebhook, verifyWebhook };
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map