@flow-industries/id 0.26.5 → 0.27.0

package/contracts/v1/sdk-exports.json

@@ -197,6 +197,11 @@
         "type": false,
         "value": true
       },
+      {
+        "name": "createGitHubConnector",
+        "type": false,
+        "value": true
+      },
       {
         "name": "createNoteTransport",
         "type": false,
@@ -367,6 +372,86 @@
         "type": false,
         "value": true
       },
+      {
+        "name": "GITHUB_BASELINE_SCOPES",
+        "type": false,
+        "value": true
+      },
+      {
+        "name": "GITHUB_REQUESTABLE_SCOPES",
+        "type": false,
+        "value": true
+      },
+      {
+        "name": "GITHUB_SCOPE_DESCRIPTIONS",
+        "type": false,
+        "value": true
+      },
+      {
+        "name": "GitHubConnector",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "GitHubConnectorCallOptions",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "GitHubConnectorError",
+        "type": true,
+        "value": true
+      },
+      {
+        "name": "GitHubConnectorErrorCode",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "GitHubConnectorFailure",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "GitHubConnectorOptions",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "GitHubConnectorResult",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "githubConsentUrl",
+        "type": false,
+        "value": true
+      },
+      {
+        "name": "GitHubOperationData",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "GitHubOperationId",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "GitHubOperationInput",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "GitHubScope",
+        "type": true,
+        "value": false
+      },
+      {
+        "name": "hasGitHubScope",
+        "type": false,
+        "value": true
+      },
       {
         "name": "hitLabel",
         "type": false,

package/dist/sdk/client/github-connector.d.ts

@@ -0,0 +1,19 @@
+import { type GitHubScope } from "../github/scopes";
+import type { GitHubConnector, GitHubConnectorErrorCode, GitHubConnectorFailure, GitHubConnectorOptions } from "../types/github-connector";
+/** A refused connector call. `consentUrl` is set when the user can fix it in
+ * Flow ID: connecting GitHub, reconnecting, or granting `requiredScopes`. */
+export declare class GitHubConnectorError extends Error {
+    readonly status: number;
+    readonly code: GitHubConnectorErrorCode;
+    readonly requiredScopes: GitHubScope[];
+    readonly consentUrl?: string;
+    readonly retryAfter?: number;
+    readonly fields: string[];
+    constructor(status: number, failure: GitHubConnectorFailure, options?: ErrorOptions);
+}
+/**
+ * Calls GitHub through Flow ID as the signed-in user. Flow ID holds the
+ * user's GitHub grant and answers with projected data, so the app never sees
+ * a GitHub token. The app's origin must be on Flow ID's connector allow-list.
+ */
+export declare function createGitHubConnector(host: string, getToken: () => Promise<string | null>, getUserId: () => string | null, options?: GitHubConnectorOptions): GitHubConnector;

package/dist/sdk/client/github-connector.js

@@ -0,0 +1,128 @@
+import { z } from "zod";
+import { githubConsentUrl, isGitHubScope, } from "../github/scopes";
+/** A refused connector call. `consentUrl` is set when the user can fix it in
+ * Flow ID: connecting GitHub, reconnecting, or granting `requiredScopes`. */
+export class GitHubConnectorError extends Error {
+    status;
+    code;
+    requiredScopes;
+    consentUrl;
+    retryAfter;
+    fields;
+    constructor(status, failure, options) {
+        super(failure.code, options);
+        this.status = status;
+        this.name = "GitHubConnectorError";
+        this.code = failure.code;
+        this.requiredScopes = failure.requiredScopes ?? [];
+        this.consentUrl = failure.consentUrl;
+        this.retryAfter = failure.retryAfter;
+        this.fields = failure.fields ?? [];
+    }
+}
+const failureSchema = z.object({
+    code: z.string().max(64),
+    requiredScopes: z.array(z.string().max(64)).max(16).optional(),
+    consentUrl: z.string().max(2048).optional(),
+    retryAfter: z.number().int().min(0).max(3600).optional(),
+    fields: z.array(z.string().max(256)).max(20).optional(),
+});
+const knownCodes = new Set([
+    "GITHUB_CONNECTOR_DISABLED",
+    "ORIGIN_DENIED",
+    "SIGN_IN_REQUIRED",
+    "ACCOUNT_CHANGED",
+    "RATE_LIMITED",
+    "UNKNOWN_OPERATION",
+    "INVALID_BODY",
+    "TOO_LARGE",
+    "GITHUB_NOT_CONNECTED",
+    "GITHUB_RECONNECT_REQUIRED",
+    "GITHUB_SCOPE_REQUIRED",
+    "GITHUB_RATE_LIMITED",
+    "GITHUB_NOT_FOUND",
+    "GITHUB_FORBIDDEN",
+    "GITHUB_CONFLICT",
+    "GITHUB_VALIDATION_FAILED",
+    "GITHUB_UNAVAILABLE",
+    "GITHUB_INVALID_RESPONSE",
+]);
+function isKnownCode(code) {
+    return knownCodes.has(code);
+}
+const successSchema = z.object({
+    data: z.unknown(),
+    nextPage: z.number().int().min(1).max(1000).nullable(),
+});
+/**
+ * Calls GitHub through Flow ID as the signed-in user. Flow ID holds the
+ * user's GitHub grant and answers with projected data, so the app never sees
+ * a GitHub token. The app's origin must be on Flow ID's connector allow-list.
+ */
+export function createGitHubConnector(host, getToken, getUserId, options = {}) {
+    // Never call `fetch` as a method of another object: Chrome throws
+    // "Illegal invocation" for any receiver other than the window.
+    const send = options.fetch ??
+        ((input, init) => globalThis.fetch(input, init));
+    const consentUrl = (scopes = []) => githubConsentUrl(host, scopes);
+    return {
+        async call(operation, input, callOptions = {}) {
+            const userId = getUserId();
+            const token = userId ? await getToken() : null;
+            if (!userId || !token)
+                throw new GitHubConnectorError(401, { code: "SIGN_IN_REQUIRED" });
+            let response;
+            try {
+                response = await send(`${host}/api/connectors/github/${encodeURIComponent(operation)}`, {
+                    method: "POST",
+                    headers: {
+                        Authorization: `Bearer ${token}`,
+                        "Content-Type": "application/json",
+                        "X-Flow-User-Id": userId,
+                    },
+                    body: JSON.stringify(input),
+                    signal: callOptions.signal,
+                });
+            }
+            catch (error) {
+                callOptions.signal?.throwIfAborted();
+                throw new GitHubConnectorError(0, { code: "CONNECTOR_UNAVAILABLE" }, {
+                    cause: error,
+                });
+            }
+            const payload = await response.json().catch(() => null);
+            if (getUserId() !== userId)
+                throw new GitHubConnectorError(409, { code: "ACCOUNT_CHANGED" });
+            if (!response.ok) {
+                const failure = failureSchema.safeParse(payload);
+                throw new GitHubConnectorError(response.status, failure.success && isKnownCode(failure.data.code)
+                    ? {
+                        ...failure.data,
+                        code: failure.data.code,
+                        requiredScopes: failure.data.requiredScopes?.filter(isGitHubScope),
+                    }
+                    : { code: "CONNECTOR_UNAVAILABLE" });
+            }
+            const success = successSchema.safeParse(payload);
+            if (!success.success)
+                throw new GitHubConnectorError(502, {
+                    code: "GITHUB_INVALID_RESPONSE",
+                });
+            /* SAFETY: Flow ID validated `data` against this operation's response schema
+               before answering; the SDK names that contract rather than re-validating it. */
+            return success.data;
+        },
+        consentUrl,
+        requestScopes(scopes = []) {
+            if (!("window" in globalThis))
+                return null;
+            // Open blank first so the opener link is cut before Flow ID loads.
+            const opened = window.open("about:blank", "_blank");
+            if (!opened)
+                return null;
+            opened.opener = null;
+            opened.location.href = consentUrl(scopes);
+            return opened;
+        },
+    };
+}

package/dist/sdk/client/index.d.ts

@@ -1,5 +1,7 @@
+export { GITHUB_BASELINE_SCOPES, GITHUB_REQUESTABLE_SCOPES, GITHUB_SCOPE_DESCRIPTIONS, githubConsentUrl, hasGitHubScope, } from "../github/scopes";
 export { defaultIdHost, isLocalHostname } from "../id-host";
 export type { AccessKeyOptions, ActionCatalogEntry, ActionCatalogResponse, ActionCurve, ActionEventRequest, ActionEventResponse, ActionSubjectRef, ActionSurface, ActionsApi, ActionTransitionKind, ActiveAction, ActiveActionResponse, ActiveSessionConflict, AdditionalSession, Address, AtprotoApi, AtprotoResolution, AtprotoResolutionFailure, AtprotoResolveOptions, BrowserAccount, BrowserAccounts, CatalogFieldRef, ClockAnchor, ConnectCapabilities, ConnectResponse, CreateFlowOptions, CreateStudySubjectInput, CurrentAction, DialogHost, FinishActionRequest, FinishActionResponse, FinishedSummary, Flow, FlowCredential, FlowSessionState, FlowState, FlowUser, FlowWidgetHandle, FlowWidgetName, FocusApi, FocusPhase, FocusSessionEvent, FocusSessionState, ListStudySessionsOptions, ListStudySubjectsOptions, LoginOptions, MarkNotificationsReadInput, MethodName, MountFlowWidgetOptions, MountProfileOptions, NotificationCounts, NotificationEntry, NotificationPage, NotificationReadResult, NotificationRefusal, OpenProfileOptions, PasskeyPrfOptions, ProfileButtonHandle, ProfilePosition, RoomMemberEntry, Session, StartActionInput, StartActionResponse, StartActionResult, StartFocusRequest, StudyApi, StudyCatalog, StudyCategory, StudyCategoryTotals, StudyField, StudyRange, StudySearchHit, StudySessionEntry, StudySessionPage, StudySubject, StudySubjectList, StudySubjectRefusal, StudySubjectRemovalResponse, StudySubjectResponse, StudySubjectTotals, StudySummary, SwitchAccountOptions, UpdateStudySubjectInput, UserActionSurface, XpEstimateContext, XpMode, } from "../types";
+export type { GitHubConnector, GitHubConnectorCallOptions, GitHubConnectorErrorCode, GitHubConnectorFailure, GitHubConnectorOptions, GitHubConnectorResult, GitHubOperationData, GitHubOperationId, GitHubOperationInput, GitHubScope, } from "../types/github-connector";
 export type { NoteBlob, NoteCollection, NoteOperation, NoteRecord, NoteResponses, NoteStoredRecord, NoteVaultHeader, } from "../types/note-transport";
 export { consistencyCurve, estimateActionXp, FLOW_SCORE_MAX, flowMultiplier, } from "../xp/curve";
 export { ActionsRequestError, createActionsApi, isActiveSessionConflict, } from "./actions";
@@ -8,6 +10,7 @@ export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { createFlowWidget } from "./flow-widget";
 export { actionHeadline, anchorFor, catalogFieldIndex, createFocusApi, elapsedSeconds, fieldsCoveredBySubjects, focusSessionReducer, formatElapsed, hitLabel, INITIAL_FOCUS_STATE, MEDITATION_SOURCE, matchScore, normalizeSearchText, REANCHOR_TOLERANCE_SECONDS, recentSubjects, STUDY_SOURCE, searchStudy, shouldReanchor, } from "./focus";
+export { createGitHubConnector, GitHubConnectorError, } from "./github-connector";
 export { METHODS } from "./methods";
 export { createNoteTransport, NoteTransportError } from "./note-transport";
 export { closeProfile, openProfile } from "./open-profile";

package/dist/sdk/client/index.js

@@ -1,3 +1,4 @@
+export { GITHUB_BASELINE_SCOPES, GITHUB_REQUESTABLE_SCOPES, GITHUB_SCOPE_DESCRIPTIONS, githubConsentUrl, hasGitHubScope, } from "../github/scopes";
 export { defaultIdHost, isLocalHostname } from "../id-host";
 export { consistencyCurve, estimateActionXp, FLOW_SCORE_MAX, flowMultiplier, } from "../xp/curve";
 export { ActionsRequestError, createActionsApi, isActiveSessionConflict, } from "./actions";
@@ -6,6 +7,7 @@ export { createFlow, getFlow, requireFlow, resetFlow } from "./create-flow";
 export { createDialogHost } from "./dialog-host";
 export { createFlowWidget } from "./flow-widget";
 export { actionHeadline, anchorFor, catalogFieldIndex, createFocusApi, elapsedSeconds, fieldsCoveredBySubjects, focusSessionReducer, formatElapsed, hitLabel, INITIAL_FOCUS_STATE, MEDITATION_SOURCE, matchScore, normalizeSearchText, REANCHOR_TOLERANCE_SECONDS, recentSubjects, STUDY_SOURCE, searchStudy, shouldReanchor, } from "./focus";
+export { createGitHubConnector, GitHubConnectorError, } from "./github-connector";
 export { METHODS } from "./methods";
 export { createNoteTransport, NoteTransportError } from "./note-transport";
 export { closeProfile, openProfile } from "./open-profile";

package/dist/sdk/client/oauth.d.ts

@@ -0,0 +1,9 @@
+import type { OAuthCompletion, OAuthStartRequest, OAuthStatus } from "../types";
+/** The provider a hosted-page or account-page URL is returning from, if any. */
+export declare function oauthReturnProvider(search: string): string | null;
+export declare function getOAuthStatus(provider: string, signal?: AbortSignal): Promise<OAuthStatus>;
+export declare function unlinkOAuth(provider: string, expectedUserId: string): Promise<void>;
+/** Starts authorization and leaves the page for the provider; resolves only on failure paths. */
+export declare function startOAuth(provider: string, request: OAuthStartRequest, signal: AbortSignal): Promise<void>;
+/** Finishes the attempt this tab started; memoized so a re-render cannot spend the token twice. */
+export declare function completeOAuth(provider: string): Promise<OAuthCompletion>;

package/dist/sdk/client/oauth.js

@@ -0,0 +1,68 @@
+/** The provider a hosted-page or account-page URL is returning from, if any. */
+export function oauthReturnProvider(search) {
+    return new URLSearchParams(search).get("oauth");
+}
+const endpoint = (provider, action) => `/api/auth/oauth/${encodeURIComponent(provider)}/${action}`;
+const completionKey = (provider) => `flow.oauth.completion.${provider}`;
+async function readResponse(response) {
+    const body = await response.json().catch(() => ({}));
+    if (!response.ok)
+        throw new Error(body.message ?? body.error ?? "Could not connect your account.");
+    // SAFETY: the caller names the payload returned by the same-origin Flow endpoint.
+    return body;
+}
+export async function getOAuthStatus(provider, signal) {
+    return readResponse(await fetch(endpoint(provider, "status"), {
+        credentials: "include",
+        signal,
+    }));
+}
+export async function unlinkOAuth(provider, expectedUserId) {
+    await readResponse(await fetch(endpoint(provider, "unlink"), {
+        method: "POST",
+        credentials: "include",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ expectedUserId }),
+    }));
+}
+/** Starts authorization and leaves the page for the provider; resolves only on failure paths. */
+export async function startOAuth(provider, request, signal) {
+    signal.throwIfAborted();
+    const result = await readResponse(await fetch(endpoint(provider, "start"), {
+        method: "POST",
+        credentials: "include",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(request),
+        signal,
+    }));
+    signal.throwIfAborted();
+    sessionStorage.setItem(completionKey(provider), result.completionToken);
+    window.location.assign(result.url);
+}
+const completions = new Map();
+/** Finishes the attempt this tab started; memoized so a re-render cannot spend the token twice. */
+export function completeOAuth(provider) {
+    const existing = completions.get(provider);
+    if (existing)
+        return existing;
+    const completionToken = sessionStorage.getItem(completionKey(provider));
+    if (!completionToken)
+        return Promise.reject(new Error("Sign-in expired. Please try again."));
+    const completion = fetch(endpoint(provider, "complete"), {
+        method: "POST",
+        credentials: "include",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ completionToken }),
+    })
+        .then(async (response) => {
+        if (response.status === 202)
+            throw new Error("Authorization is still finishing. Please try again.");
+        return readResponse(response);
+    })
+        .then((result) => {
+        sessionStorage.removeItem(completionKey(provider));
+        return result;
+    });
+    completions.set(provider, completion);
+    return completion;
+}