@rawdash/connector-workos 0.0.1

package/dist/index.js

@@ -0,0 +1,610 @@
+// ../../connector-shared/dist/index.js
+var HTTP_CLIENT_VERSION = "0.0.0";
+var DEFAULT_USER_AGENT = `rawdash-connector/${HTTP_CLIENT_VERSION} (+https://rawdash.dev)`;
+function connectorUserAgent(connectorId) {
+  return `rawdash-connector-${connectorId}/${HTTP_CLIENT_VERSION} (+https://rawdash.dev)`;
+}
+function parseEpoch(value, unit) {
+  if (value === null || value === void 0) {
+    return null;
+  }
+  if (unit === "iso") {
+    if (typeof value !== "string") {
+      return null;
+    }
+    const ms = new Date(value).getTime();
+    return Number.isFinite(ms) ? ms : null;
+  }
+  if (typeof value === "string" && value.trim() === "") {
+    return null;
+  }
+  const n = typeof value === "number" ? value : Number(value);
+  if (!Number.isFinite(n)) {
+    return null;
+  }
+  const result = unit === "s" ? n * 1e3 : n;
+  return Number.isFinite(result) ? result : null;
+}
+
+// src/workos.ts
+import {
+  BaseConnector,
+  defineConfigFields,
+  defineConnectorDoc,
+  defineResources,
+  makeChunkedCursorGuard,
+  paginateChunked,
+  schemasFromResources,
+  selectActivePhases
+} from "@rawdash/core";
+import { z } from "zod";
+var configFields = defineConfigFields(
+  z.object({
+    apiKey: z.object({ $secret: z.string().min(1) }).meta({
+      label: "API key",
+      description: "WorkOS API key (server-side, starts with `sk_`). Used as a bearer token on every request. Read-only access is sufficient for sync.",
+      placeholder: "WORKOS_API_KEY",
+      secret: true
+    }),
+    resources: z.array(
+      z.enum(["organizations", "connections", "directories", "auth_events"])
+    ).nonempty().optional().meta({
+      label: "Resources",
+      description: "Which WorkOS resources to sync. Omit to sync all of them."
+    }),
+    authEventsLookbackDays: z.number().int().positive().max(90).optional().meta({
+      label: "Auth events lookback (days)",
+      description: "On a full sync (and when no incremental cursor is available), how many days of authentication events to fetch. Defaults to 30. Caps at 90.",
+      placeholder: "30"
+    })
+  })
+);
+var doc = defineConnectorDoc({
+  displayName: "WorkOS",
+  category: "security",
+  brandColor: "#6363F1",
+  tagline: "Sync organizations, SSO connections, directory-sync directories, and authentication events from a WorkOS workspace for B2B SaaS onboarding and SSO-activity dashboards.",
+  vendor: {
+    name: "WorkOS",
+    domain: "workos.com",
+    apiDocs: "https://workos.com/docs/reference",
+    website: "https://workos.com"
+  },
+  auth: {
+    summary: "A WorkOS API key (server-side, starts with `sk_`) is required. It is sent as a bearer token on every request and never leaves the workspace.",
+    setup: [
+      "Sign in to the WorkOS Dashboard and switch to the environment (Sandbox or Production) you want to sync.",
+      "Open API Keys in the left navigation.",
+      "Create a new secret key (or copy an existing one). WorkOS only shows the secret once on creation.",
+      'Store it as a rawdash secret and reference it from the connector config as `apiKey: secret("WORKOS_API_KEY")`.'
+    ]
+  },
+  rateLimit: "WorkOS list endpoints return X-RateLimit-Remaining and X-RateLimit-Reset (Unix seconds) headers when throttling kicks in; the shared HTTP client falls back to Retry-After on 429.",
+  limitations: [
+    "Authentication events use the WorkOS Events API filtered to authentication.* event types (sign-in success and failure across SSO, OAuth, password, magic auth, MFA). Other event categories (dsync.*, organization.*) are not synced.",
+    "Organizations, connections, and directories are fetched in full on every sync; the WorkOS list endpoints do not expose a server-side updated_at filter, so the scope is cleared and rewritten on full syncs and left untouched on incremental syncs.",
+    "Directory-sync user and group rows are out of scope; this connector tracks the directory entities themselves, not their imported memberships."
+  ]
+});
+var workosCredentials = {
+  apiKey: {
+    description: "WorkOS API key",
+    auth: "required"
+  }
+};
+var PHASE_ORDER = [
+  "organizations",
+  "connections",
+  "directories",
+  "auth_events"
+];
+var isWorkOSSyncCursor = makeChunkedCursorGuard(PHASE_ORDER);
+var ORGANIZATION_ENTITY = "workos_organization";
+var CONNECTION_ENTITY = "workos_connection";
+var DIRECTORY_ENTITY = "workos_directory";
+var AUTH_EVENT = "workos_auth_event";
+var PAGE_SIZE = 100;
+var DEFAULT_AUTH_LOOKBACK_DAYS = 30;
+var BASE_URL = "https://api.workos.com";
+var AUTH_EVENT_TYPES = [
+  "authentication.email_verification_succeeded",
+  "authentication.magic_auth_succeeded",
+  "authentication.magic_auth_failed",
+  "authentication.mfa_succeeded",
+  "authentication.mfa_failed",
+  "authentication.oauth_succeeded",
+  "authentication.oauth_failed",
+  "authentication.password_succeeded",
+  "authentication.password_failed",
+  "authentication.sso_succeeded",
+  "authentication.sso_failed"
+];
+var idString = z.string().min(1);
+var listMetadataSchema = z.object({
+  before: z.string().nullish(),
+  after: z.string().nullish()
+});
+var organizationDomainSchema = z.object({
+  domain: z.string(),
+  state: z.string().nullish()
+});
+var organizationSchema = z.object({
+  id: idString,
+  name: z.string(),
+  domains: z.array(organizationDomainSchema).nullish(),
+  allow_profiles_outside_organization: z.boolean().nullish(),
+  created_at: z.string(),
+  updated_at: z.string().nullish()
+});
+var organizationsResponseSchema = z.object({
+  data: z.array(organizationSchema),
+  list_metadata: listMetadataSchema
+});
+var connectionSchema = z.object({
+  id: idString,
+  name: z.string(),
+  organization_id: z.string().nullish(),
+  connection_type: z.string(),
+  state: z.string().nullish(),
+  status: z.string().nullish(),
+  created_at: z.string(),
+  updated_at: z.string().nullish()
+});
+var connectionsResponseSchema = z.object({
+  data: z.array(connectionSchema),
+  list_metadata: listMetadataSchema
+});
+var directorySchema = z.object({
+  id: idString,
+  name: z.string(),
+  organization_id: z.string().nullish(),
+  type: z.string(),
+  state: z.string().nullish(),
+  created_at: z.string(),
+  updated_at: z.string().nullish()
+});
+var directoriesResponseSchema = z.object({
+  data: z.array(directorySchema),
+  list_metadata: listMetadataSchema
+});
+var eventSchema = z.object({
+  id: idString,
+  event: z.string(),
+  created_at: z.string(),
+  data: z.object({
+    organization_id: z.string().nullish(),
+    user_id: z.string().nullish(),
+    email: z.string().nullish(),
+    ip_address: z.string().nullish(),
+    connection_id: z.string().nullish(),
+    connection_type: z.string().nullish()
+  }).passthrough().nullish()
+});
+var eventsResponseSchema = z.object({
+  data: z.array(eventSchema),
+  list_metadata: listMetadataSchema
+});
+var workosResources = defineResources({
+  [ORGANIZATION_ENTITY]: {
+    shape: "entity",
+    filterable: [],
+    description: "WorkOS organizations (tenants) with their display name, domains, and creation timestamp.",
+    endpoint: "GET /organizations",
+    fields: [
+      { name: "name", description: "Organization display name." },
+      {
+        name: "domains",
+        description: "Comma-separated list of domains attached to the organization."
+      },
+      {
+        name: "createdAt",
+        description: "When the organization was created (Unix ms)."
+      }
+    ],
+    responses: { organizations: organizationsResponseSchema }
+  },
+  [CONNECTION_ENTITY]: {
+    shape: "entity",
+    filterable: [
+      {
+        field: "state",
+        ops: ["eq"],
+        values: ["active", "inactive", "draft", "linked", "unlinked"]
+      },
+      { field: "connectionType", ops: ["eq"] }
+    ],
+    description: "WorkOS SSO connections (one per identity provider per organization) with their type, state, and parent organization.",
+    endpoint: "GET /connections",
+    fields: [
+      {
+        name: "connectionType",
+        description: "Connection type (e.g. OktaSAML, AzureSAML, GoogleOAuth)."
+      },
+      {
+        name: "organizationId",
+        description: "WorkOS organization that owns the connection."
+      },
+      {
+        name: "state",
+        description: "Lifecycle state (active, inactive, draft, linked, unlinked)."
+      },
+      { name: "name", description: "Connection display name." },
+      {
+        name: "createdAt",
+        description: "When the connection was created (Unix ms)."
+      }
+    ],
+    responses: { connections: connectionsResponseSchema }
+  },
+  [DIRECTORY_ENTITY]: {
+    shape: "entity",
+    filterable: [
+      {
+        field: "state",
+        ops: ["eq"],
+        values: ["active", "inactive", "validating", "linked", "unlinked"]
+      },
+      { field: "directoryType", ops: ["eq"] }
+    ],
+    description: "WorkOS directory-sync directories (SCIM/HRIS feeds) with their type, state, and parent organization.",
+    endpoint: "GET /directories",
+    fields: [
+      {
+        name: "directoryType",
+        description: "Directory provider type (e.g. okta scim v2.0, azure scim v2.0, bamboohr)."
+      },
+      {
+        name: "organizationId",
+        description: "WorkOS organization that owns the directory."
+      },
+      {
+        name: "state",
+        description: "Lifecycle state (active, inactive, validating, linked, unlinked)."
+      },
+      { name: "name", description: "Directory display name." },
+      {
+        name: "createdAt",
+        description: "When the directory was created (Unix ms)."
+      }
+    ],
+    responses: { directories: directoriesResponseSchema }
+  },
+  [AUTH_EVENT]: {
+    shape: "event",
+    filterable: [
+      { field: "eventType", ops: ["eq"], values: [...AUTH_EVENT_TYPES] }
+    ],
+    description: "Authentication events from the WorkOS Events API (SSO, OAuth, password, magic auth, and MFA sign-in successes and failures).",
+    endpoint: "GET /events",
+    notes: "Filtered to the authentication.* event family. Incremental syncs pass `range_start` so only events newer than the watermark are returned.",
+    fields: [
+      {
+        name: "eventType",
+        description: "WorkOS event name (authentication.sso_succeeded, etc)."
+      },
+      {
+        name: "outcome",
+        description: '"succeeded" or "failed" derived from the event suffix.'
+      },
+      {
+        name: "method",
+        description: "Authentication method (sso, oauth, password, magic_auth, mfa, email_verification)."
+      },
+      {
+        name: "organizationId",
+        description: "WorkOS organization the event belongs to (may be null)."
+      },
+      {
+        name: "userId",
+        description: "WorkOS user id involved in the event (may be null)."
+      },
+      {
+        name: "connectionId",
+        description: "WorkOS connection id used for the event (may be null)."
+      },
+      {
+        name: "connectionType",
+        description: "Connection type used for the event (may be null for non-SSO methods)."
+      },
+      {
+        name: "ipAddress",
+        description: "Client IP captured by WorkOS (may be null)."
+      }
+    ],
+    responses: { auth_events: eventsResponseSchema }
+  }
+});
+var id = "workos";
+function isoToMs(value) {
+  if (!value) {
+    return null;
+  }
+  return parseEpoch(value, "iso");
+}
+function isoToMsOrZero(value) {
+  return isoToMs(value) ?? 0;
+}
+function summarizeDomains(domains) {
+  if (!domains || domains.length === 0) {
+    return null;
+  }
+  return domains.map((d) => d.domain).join(", ");
+}
+function deriveOutcome(eventType) {
+  if (eventType.endsWith("_succeeded")) {
+    return "succeeded";
+  }
+  if (eventType.endsWith("_failed")) {
+    return "failed";
+  }
+  return null;
+}
+function deriveMethod(eventType) {
+  const m = /^authentication\.(.+?)_(?:succeeded|failed)$/.exec(eventType);
+  return m ? m[1] : null;
+}
+function isAuthEventType(value) {
+  return AUTH_EVENT_TYPES.includes(value);
+}
+function lookbackStartIso(days) {
+  const ts = Date.now() - days * 24 * 60 * 60 * 1e3;
+  return new Date(ts).toISOString();
+}
+var WorkOSConnector = class _WorkOSConnector extends BaseConnector {
+  static id = id;
+  static resources = workosResources;
+  static schemas = schemasFromResources(workosResources);
+  static create(input, ctx) {
+    const parsed = configFields.parse(input);
+    return new _WorkOSConnector(
+      {
+        resources: parsed.resources,
+        authEventsLookbackDays: parsed.authEventsLookbackDays
+      },
+      { apiKey: parsed.apiKey },
+      ctx
+    );
+  }
+  id = id;
+  credentials = workosCredentials;
+  buildHeaders() {
+    return {
+      Authorization: `Bearer ${this.creds.apiKey}`,
+      Accept: "application/json",
+      "User-Agent": connectorUserAgent("workos")
+    };
+  }
+  apiGet(url, resource, signal) {
+    return this.get(url, {
+      resource,
+      headers: this.buildHeaders(),
+      signal
+    });
+  }
+  buildListUrl(path, after, extra = {}) {
+    const url = new URL(`${BASE_URL}${path}`);
+    url.searchParams.set("limit", String(PAGE_SIZE));
+    url.searchParams.set("order", "asc");
+    if (after) {
+      url.searchParams.set("after", after);
+    }
+    for (const [k, v] of Object.entries(extra)) {
+      url.searchParams.append(k, v);
+    }
+    return url.toString();
+  }
+  buildEventsUrl(after, options) {
+    const url = new URL(`${BASE_URL}/events`);
+    url.searchParams.set("limit", String(PAGE_SIZE));
+    for (const t of AUTH_EVENT_TYPES) {
+      url.searchParams.append("events", t);
+    }
+    if (after) {
+      url.searchParams.set("after", after);
+    } else {
+      const rangeStart = options.since ?? this.defaultEventsRangeStart();
+      url.searchParams.set("range_start", rangeStart);
+    }
+    return url.toString();
+  }
+  defaultEventsRangeStart() {
+    const days = this.settings.authEventsLookbackDays ?? DEFAULT_AUTH_LOOKBACK_DAYS;
+    return lookbackStartIso(days);
+  }
+  async fetchOrganizationsPage(page, signal) {
+    const url = this.buildListUrl("/organizations", page);
+    const res = await this.apiGet(
+      url,
+      "organizations",
+      signal
+    );
+    const next = res.body.list_metadata.after ?? null;
+    return { items: res.body.data, next };
+  }
+  async fetchConnectionsPage(page, signal) {
+    const url = this.buildListUrl("/connections", page);
+    const res = await this.apiGet(
+      url,
+      "connections",
+      signal
+    );
+    const next = res.body.list_metadata.after ?? null;
+    return { items: res.body.data, next };
+  }
+  async fetchDirectoriesPage(page, signal) {
+    const url = this.buildListUrl("/directories", page);
+    const res = await this.apiGet(
+      url,
+      "directories",
+      signal
+    );
+    const next = res.body.list_metadata.after ?? null;
+    return { items: res.body.data, next };
+  }
+  async fetchEventsPage(page, options, signal) {
+    const url = this.buildEventsUrl(page, options);
+    const res = await this.apiGet(url, "auth_events", signal);
+    const next = res.body.list_metadata.after ?? null;
+    return { items: res.body.data, next };
+  }
+  async fetchPhasePage(phase, page, options, signal) {
+    switch (phase) {
+      case "organizations":
+        return this.fetchOrganizationsPage(page, signal);
+      case "connections":
+        return this.fetchConnectionsPage(page, signal);
+      case "directories":
+        return this.fetchDirectoriesPage(page, signal);
+      case "auth_events":
+        return this.fetchEventsPage(page, options, signal);
+    }
+  }
+  async writeOrganizations(storage, items) {
+    for (const org of items) {
+      await storage.entity({
+        type: ORGANIZATION_ENTITY,
+        id: org.id,
+        attributes: {
+          name: org.name,
+          domains: summarizeDomains(org.domains),
+          createdAt: isoToMs(org.created_at)
+        },
+        updated_at: isoToMsOrZero(org.updated_at ?? org.created_at)
+      });
+    }
+  }
+  async writeConnections(storage, items) {
+    for (const c of items) {
+      await storage.entity({
+        type: CONNECTION_ENTITY,
+        id: c.id,
+        attributes: {
+          name: c.name,
+          connectionType: c.connection_type,
+          organizationId: c.organization_id ?? null,
+          state: c.state ?? c.status ?? null,
+          createdAt: isoToMs(c.created_at)
+        },
+        updated_at: isoToMsOrZero(c.updated_at ?? c.created_at)
+      });
+    }
+  }
+  async writeDirectories(storage, items) {
+    for (const d of items) {
+      await storage.entity({
+        type: DIRECTORY_ENTITY,
+        id: d.id,
+        attributes: {
+          name: d.name,
+          directoryType: d.type,
+          organizationId: d.organization_id ?? null,
+          state: d.state ?? null,
+          createdAt: isoToMs(d.created_at)
+        },
+        updated_at: isoToMsOrZero(d.updated_at ?? d.created_at)
+      });
+    }
+  }
+  async writeAuthEvents(storage, items, sinceMs) {
+    for (const ev of items) {
+      if (!isAuthEventType(ev.event)) {
+        continue;
+      }
+      const ts = isoToMs(ev.created_at);
+      if (ts === null) {
+        continue;
+      }
+      if (sinceMs !== null && ts <= sinceMs) {
+        continue;
+      }
+      const data = ev.data ?? {};
+      const attributes = {
+        eventType: ev.event,
+        outcome: deriveOutcome(ev.event),
+        method: deriveMethod(ev.event),
+        organizationId: data.organization_id ?? null,
+        userId: data.user_id ?? null,
+        connectionId: data.connection_id ?? null,
+        connectionType: data.connection_type ?? null,
+        ipAddress: data.ip_address ?? null,
+        eventId: ev.id
+      };
+      await storage.event({
+        name: AUTH_EVENT,
+        start_ts: ts,
+        end_ts: null,
+        attributes
+      });
+    }
+  }
+  async clearScopeOnFirstPage(storage, phase, isFull) {
+    if (!isFull) {
+      return;
+    }
+    switch (phase) {
+      case "organizations":
+        await storage.entities([], { types: [ORGANIZATION_ENTITY] });
+        return;
+      case "connections":
+        await storage.entities([], { types: [CONNECTION_ENTITY] });
+        return;
+      case "directories":
+        await storage.entities([], { types: [DIRECTORY_ENTITY] });
+        return;
+      case "auth_events":
+        await storage.events([], { names: [AUTH_EVENT] });
+        return;
+    }
+  }
+  async writePhase(storage, phase, items, sinceMs) {
+    switch (phase) {
+      case "organizations":
+        return this.writeOrganizations(storage, items);
+      case "connections":
+        return this.writeConnections(storage, items);
+      case "directories":
+        return this.writeDirectories(storage, items);
+      case "auth_events":
+        return this.writeAuthEvents(storage, items, sinceMs);
+    }
+  }
+  resolveCursor(cursor) {
+    return isWorkOSSyncCursor(cursor) ? cursor : void 0;
+  }
+  async sync(options, storage, signal) {
+    const cursor = this.resolveCursor(options.cursor);
+    const isFull = options.mode === "full";
+    const sinceMs = options.since ? Date.parse(options.since) : null;
+    const sinceMsOrNull = sinceMs !== null && Number.isFinite(sinceMs) ? sinceMs : null;
+    const phases = selectActivePhases(
+      (r) => r,
+      PHASE_ORDER,
+      this.settings.resources
+    );
+    return paginateChunked({
+      phases,
+      cursor,
+      signal,
+      logger: this.logger,
+      fetchPage: async (phase, page, sig) => this.fetchPhasePage(phase, page, options, sig),
+      writeBatch: async (phase, items, page) => {
+        if (page === null) {
+          await this.clearScopeOnFirstPage(storage, phase, isFull);
+        }
+        await this.writePhase(storage, phase, items, sinceMsOrNull);
+      }
+    });
+  }
+};
+
+// src/index.ts
+var index_default = WorkOSConnector;
+export {
+  WorkOSConnector,
+  configFields,
+  index_default as default,
+  doc,
+  id,
+  workosResources as resources
+};
+//# sourceMappingURL=index.js.map