@pellux/goodvibes-sdk 0.38.0 → 1.0.0

package/dist/platform/calendar/microsoft-graph-api.js

@@ -0,0 +1,95 @@
+/**
+ * microsoft-graph-api.ts — the Microsoft Graph client over an access token and the
+ * injected HttpFetch. Lists calendars (me/calendars), lists events over a window
+ * (me/calendars/{id}/calendarView, which returns expanded instances), and creates
+ * events (me/calendars/{id}/events). A Prefer: outlook.timezone="UTC" header makes
+ * Graph return UTC wall times so normalization is honest. Paging follows
+ * @odata.nextLink; failures are named degraded states via CalendarApiError.
+ */
+import { authedRequest } from './calendar-api-shared.js';
+import { normalizeGraphEvent } from './merged-calendar-model.js';
+const BASE = 'https://graph.microsoft.com/v1.0';
+const UTC_PREFER = { Prefer: 'outlook.timezone="UTC"' };
+/** List the user's calendars; write access comes from canEdit. */
+export async function listGraphCalendars(fetchImpl, token) {
+    const out = [];
+    let next = `${BASE}/me/calendars?$select=id,name,canEdit,isDefaultCalendar&$top=100`;
+    while (next) {
+        const body = (await authedRequest(fetchImpl, 'microsoft', { url: next, method: 'GET', token }));
+        for (const raw of body.value ?? []) {
+            const item = (raw ?? {});
+            if (typeof item.id !== 'string')
+                continue;
+            out.push({
+                id: item.id,
+                name: typeof item.name === 'string' ? item.name : item.id,
+                provider: 'microsoft',
+                ...(item.isDefaultCalendar === true ? { primary: true } : {}),
+                canWrite: item.canEdit === true,
+            });
+        }
+        next = typeof body['@odata.nextLink'] === 'string' ? body['@odata.nextLink'] : undefined;
+    }
+    return out;
+}
+/** List events over a window via calendarView, paging @odata.nextLink to exhaustion. */
+export async function listGraphEvents(fetchImpl, token, query) {
+    const out = [];
+    const first = new URL(`${BASE}/me/calendars/${encodeURIComponent(query.calendarId)}/calendarView`);
+    first.searchParams.set('startDateTime', query.start);
+    first.searchParams.set('endDateTime', query.end);
+    first.searchParams.set('$select', 'id,iCalUId,subject,bodyPreview,location,start,end,isAllDay');
+    first.searchParams.set('$orderby', 'start/dateTime');
+    first.searchParams.set('$top', String(query.pageSize ?? 100));
+    let next = first.toString();
+    while (next) {
+        const body = (await authedRequest(fetchImpl, 'microsoft', {
+            url: next,
+            method: 'GET',
+            token,
+            extraHeaders: UTC_PREFER,
+        }));
+        for (const raw of body.value ?? []) {
+            const event = normalizeGraphEvent(raw, query.calendarId, query.calendarLabel);
+            if (event)
+                out.push(event);
+        }
+        next = typeof body['@odata.nextLink'] === 'string' ? body['@odata.nextLink'] : undefined;
+    }
+    return out;
+}
+/** Create an event; returns it normalized into the merged model. */
+export async function createGraphEvent(fetchImpl, token, calendarId, calendarLabel, event) {
+    const isAllDay = event.start.kind === 'date';
+    const payload = {
+        subject: event.summary,
+        isAllDay,
+        start: graphEventDate(event.start),
+        end: graphEventDate(event.end ?? event.start),
+        ...(event.location ? { location: { displayName: event.location } } : {}),
+        ...(event.description ? { body: { contentType: 'text', content: event.description } } : {}),
+    };
+    const url = `${BASE}/me/calendars/${encodeURIComponent(calendarId)}/events`;
+    const created = await authedRequest(fetchImpl, 'microsoft', {
+        url,
+        method: 'POST',
+        token,
+        body: payload,
+        extraHeaders: UTC_PREFER,
+    });
+    const normalized = normalizeGraphEvent(created, calendarId, calendarLabel);
+    if (!normalized)
+        throw new Error('Microsoft Graph accepted the event but returned an unreadable body.');
+    return normalized;
+}
+/** Map an EventDateTime to a Graph {dateTime,timeZone} object. */
+function graphEventDate(dt) {
+    if (dt.kind === 'date')
+        return { dateTime: `${dt.value}T00:00:00`, timeZone: 'UTC' };
+    if (dt.zone === 'tzid' && dt.tzid)
+        return { dateTime: stripZ(dt.value), timeZone: dt.tzid };
+    return { dateTime: stripZ(dt.value), timeZone: 'UTC' };
+}
+function stripZ(value) {
+    return value.endsWith('Z') ? value.slice(0, -1) : value;
+}

package/dist/platform/calendar/oauth-flow.d.ts

@@ -0,0 +1,62 @@
+/**
+ * oauth-flow.ts — the OAuth 2.0 machinery for calendar connectivity: the
+ * authorization-code flow with a loopback redirect and mandatory PKCE (the standard
+ * native-app pattern, RFC 8252/7636), and the device-code flow (RFC 8628) as the
+ * headless fallback. Token exchange, refresh, and revocation live here too.
+ *
+ * Every network call goes through the injected HttpFetch — this file never imports
+ * a real fetch — so the full flow runs against fake servers in tests with no real
+ * network and no real port. PKCE hashing/randomness reuse the SDK's runtime-neutral
+ * crypto adapter.
+ */
+import type { AuthCodeFlowStart, DeviceCodeFlowStart, FlowFailureReason, HttpFetch, LoopbackListenerFactory, LoopbackWaiter, ResolvedClientConfig, StoredTokenSet } from './oauth-types.js';
+/** A typed flow failure carrying the honest reason a caller surfaces to the user. */
+export declare class OAuthFlowError extends Error {
+    readonly reason: FlowFailureReason;
+    /** The provider status, when the failure came from an HTTP response. */
+    readonly status?: number;
+    constructor(reason: FlowFailureReason, message: string, status?: number);
+}
+export interface PkcePair {
+    readonly verifier: string;
+    readonly challenge: string;
+}
+/** Create a PKCE verifier + S256 challenge. */
+export declare function createPkcePair(): Promise<PkcePair>;
+/** Turn a provider token response into a StoredTokenSet, keeping a prior refresh
+ *  token when the response omits one (Google omits it on refresh). */
+export declare function parseTokenResponse(raw: unknown, now: number, priorRefreshToken?: string): StoredTokenSet;
+/**
+ * Begin the authorization-code flow: bind a loopback listener, build the PKCE
+ * authorization URL, and return both. The caller opens the URL in a browser and
+ * awaits waiter.waitForCode(), then calls completeAuthCodeFlow.
+ */
+export declare function beginAuthCodeFlow(config: ResolvedClientConfig, listenerFactory: LoopbackListenerFactory): Promise<{
+    readonly start: AuthCodeFlowStart;
+    readonly waiter: LoopbackWaiter;
+}>;
+/** Exchange an authorization code for tokens (PKCE). */
+export declare function completeAuthCodeFlow(config: ResolvedClientConfig, fetchImpl: HttpFetch, input: {
+    readonly code: string;
+    readonly verifier: string;
+    readonly redirectUri: string;
+}, now: number): Promise<StoredTokenSet>;
+/** Begin the device-code flow: request a device + user code to display. */
+export declare function beginDeviceCodeFlow(config: ResolvedClientConfig, fetchImpl: HttpFetch, now: number): Promise<DeviceCodeFlowStart>;
+/** Injected delay so device-code polling is deterministic in tests. */
+export type Sleep = (ms: number) => Promise<void>;
+/**
+ * Poll the token endpoint until the user approves the device code, the code expires,
+ * or the request is denied. Honors authorization_pending (keep polling) and slow_down
+ * (widen the interval) per RFC 8628.
+ */
+export declare function pollDeviceCodeFlow(config: ResolvedClientConfig, fetchImpl: HttpFetch, start: DeviceCodeFlowStart, clock: () => number, sleep: Sleep): Promise<StoredTokenSet>;
+/** Exchange a refresh token for a fresh access token. */
+export declare function refreshAccessToken(config: ResolvedClientConfig, fetchImpl: HttpFetch, refreshToken: string, now: number): Promise<StoredTokenSet>;
+/**
+ * Revoke a token at the provider (Google). Returns true when the provider confirms.
+ * When the provider has no revocation endpoint (Microsoft), returns false so the
+ * caller knows disconnect is local-only.
+ */
+export declare function revokeToken(config: ResolvedClientConfig, fetchImpl: HttpFetch, token: string): Promise<boolean>;
+//# sourceMappingURL=oauth-flow.d.ts.map

package/dist/platform/calendar/oauth-flow.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-flow.d.ts","sourceRoot":"","sources":["../../../src/platform/calendar/oauth-flow.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAGH,OAAO,KAAK,EACV,iBAAiB,EACjB,mBAAmB,EACnB,iBAAiB,EACjB,SAAS,EACT,uBAAuB,EACvB,cAAc,EACd,oBAAoB,EACpB,cAAc,EACf,MAAM,kBAAkB,CAAC;AAE1B,qFAAqF;AACrF,qBAAa,cAAe,SAAQ,KAAK;IACvC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAC;IACnC,wEAAwE;IACxE,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;gBACb,MAAM,EAAE,iBAAiB,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,MAAM;CAMxE;AAgBD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED,+CAA+C;AAC/C,wBAAsB,cAAc,IAAI,OAAO,CAAC,QAAQ,CAAC,CAIxD;AAwCD;sEACsE;AACtE,wBAAgB,kBAAkB,CAChC,GAAG,EAAE,OAAO,EACZ,GAAG,EAAE,MAAM,EACX,iBAAiB,CAAC,EAAE,MAAM,GACzB,cAAc,CAqBhB;AAeD;;;;GAIG;AACH,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,oBAAoB,EAC5B,eAAe,EAAE,uBAAuB,GACvC,OAAO,CAAC;IAAE,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAA;CAAE,CAAC,CAwBjF;AAED,wDAAwD;AACxD,wBAAsB,oBAAoB,CACxC,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE;IAAE,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAAC,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAAE,EACzF,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,cAAc,CAAC,CAwBzB;AAMD,2EAA2E;AAC3E,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,SAAS,EACpB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,mBAAmB,CAAC,CA2C9B;AAED,uEAAuE;AACvE,MAAM,MAAM,KAAK,GAAG,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAElD;;;;GAIG;AACH,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,mBAAmB,EAC1B,KAAK,EAAE,MAAM,MAAM,EACnB,KAAK,EAAE,KAAK,GACX,OAAO,CAAC,cAAc,CAAC,CAqCzB;AAMD,yDAAyD;AACzD,wBAAsB,kBAAkB,CACtC,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,SAAS,EACpB,YAAY,EAAE,MAAM,EACpB,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,cAAc,CAAC,CAuBzB;AAED;;;;GAIG;AACH,wBAAsB,WAAW,CAC/B,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,SAAS,EACpB,KAAK,EAAE,MAAM,GACZ,OAAO,CAAC,OAAO,CAAC,CAclB"}

package/dist/platform/calendar/oauth-flow.js

@@ -0,0 +1,305 @@
+/**
+ * oauth-flow.ts — the OAuth 2.0 machinery for calendar connectivity: the
+ * authorization-code flow with a loopback redirect and mandatory PKCE (the standard
+ * native-app pattern, RFC 8252/7636), and the device-code flow (RFC 8628) as the
+ * headless fallback. Token exchange, refresh, and revocation live here too.
+ *
+ * Every network call goes through the injected HttpFetch — this file never imports
+ * a real fetch — so the full flow runs against fake servers in tests with no real
+ * network and no real port. PKCE hashing/randomness reuse the SDK's runtime-neutral
+ * crypto adapter.
+ */
+import { createSha256Hash, randomBytesBase64url } from '../runtime/auth/crypto-adapter.js';
+/** A typed flow failure carrying the honest reason a caller surfaces to the user. */
+export class OAuthFlowError extends Error {
+    reason;
+    /** The provider status, when the failure came from an HTTP response. */
+    status;
+    constructor(reason, message, status) {
+        super(message);
+        this.name = 'OAuthFlowError';
+        this.reason = reason;
+        if (typeof status === 'number')
+            this.status = status;
+    }
+}
+function assertClientConfigured(config) {
+    if (config.isPlaceholder) {
+        throw new OAuthFlowError('client-not-configured', `No ${config.provider} client id is configured. Either this build ships no project default yet, ` +
+            'or supply your own client id under advanced settings.');
+    }
+}
+/** Create a PKCE verifier + S256 challenge. */
+export async function createPkcePair() {
+    const verifier = randomBytesBase64url(32);
+    const challenge = await createSha256Hash(verifier);
+    return { verifier, challenge };
+}
+/**
+ * A conservative fallback lifetime (seconds) used when a provider's token response
+ * omits `expires_in` or sends something we cannot parse as a positive number. Never
+ * treat that as "never expires" — an access token that silently 401s later, with no
+ * expiry recorded to trigger a proactive refresh, is worse than refreshing a bit
+ * early. One hour matches the common real-world default (Google/Microsoft both
+ * normally send 3600).
+ */
+const DEFAULT_EXPIRES_IN_SECONDS = 3600;
+/**
+ * Coerce a token response's `expires_in` into a positive number of seconds.
+ * Accepts a real number, a numeric string (some providers send `"3600"` instead of
+ * `3600`), and falls back to {@link DEFAULT_EXPIRES_IN_SECONDS} for anything else
+ * (absent, non-numeric, zero, or negative) — this build never emits a token set with
+ * no expiry at all, which the store would otherwise read as "connected forever".
+ */
+function coerceExpiresInSeconds(raw) {
+    if (typeof raw === 'number' && Number.isFinite(raw) && raw > 0)
+        return raw;
+    if (typeof raw === 'string') {
+        const parsed = Number(raw.trim());
+        if (Number.isFinite(parsed) && parsed > 0)
+            return parsed;
+    }
+    return DEFAULT_EXPIRES_IN_SECONDS;
+}
+/** Turn a provider token response into a StoredTokenSet, keeping a prior refresh
+ *  token when the response omits one (Google omits it on refresh). */
+export function parseTokenResponse(raw, now, priorRefreshToken) {
+    const json = (raw ?? {});
+    if (typeof json.access_token !== 'string' || json.access_token.length === 0) {
+        throw new OAuthFlowError('token-request-rejected', 'Token response did not include an access token.');
+    }
+    const refreshToken = typeof json.refresh_token === 'string' && json.refresh_token.length > 0
+        ? json.refresh_token
+        : priorRefreshToken;
+    const scopes = typeof json.scope === 'string' && json.scope.trim().length > 0
+        ? json.scope.trim().split(/\s+/)
+        : undefined;
+    return {
+        accessToken: json.access_token,
+        ...(refreshToken ? { refreshToken } : {}),
+        tokenType: typeof json.token_type === 'string' && json.token_type.length > 0 ? json.token_type : 'Bearer',
+        // Always set expiresAt — never omit it just because expires_in was absent or
+        // unparsable — a coerced/defaulted lifetime beats "never expires".
+        expiresAt: now + coerceExpiresInSeconds(json.expires_in) * 1000,
+        ...(scopes ? { scopes } : {}),
+        obtainedAt: now,
+    };
+}
+function formBody(payload) {
+    return new URLSearchParams(payload).toString();
+}
+async function readError(res) {
+    const body = await res.text().catch(() => '');
+    return body.length > 0 ? `${res.status}: ${body}` : `HTTP ${res.status}`;
+}
+// ---------------------------------------------------------------------------
+// Authorization-code flow
+// ---------------------------------------------------------------------------
+/**
+ * Begin the authorization-code flow: bind a loopback listener, build the PKCE
+ * authorization URL, and return both. The caller opens the URL in a browser and
+ * awaits waiter.waitForCode(), then calls completeAuthCodeFlow.
+ */
+export async function beginAuthCodeFlow(config, listenerFactory) {
+    assertClientConfigured(config);
+    const state = randomBytesBase64url(24);
+    const { verifier, challenge } = await createPkcePair();
+    const waiter = await listenerFactory({
+        expectedState: state,
+        ...(config.redirectHost ? { host: config.redirectHost } : {}),
+        ...(typeof config.redirectPort === 'number' ? { port: config.redirectPort } : {}),
+    });
+    const url = new URL(config.authorizationEndpoint);
+    url.searchParams.set('response_type', 'code');
+    url.searchParams.set('client_id', config.clientId);
+    url.searchParams.set('redirect_uri', waiter.redirectUri);
+    url.searchParams.set('state', state);
+    url.searchParams.set('scope', config.scopes.join(' '));
+    url.searchParams.set('code_challenge', challenge);
+    url.searchParams.set('code_challenge_method', 'S256');
+    for (const [key, value] of Object.entries(config.extraAuthParams ?? {})) {
+        url.searchParams.set(key, value);
+    }
+    return {
+        start: { authorizationUrl: url.toString(), state, verifier, redirectUri: waiter.redirectUri },
+        waiter,
+    };
+}
+/** Exchange an authorization code for tokens (PKCE). */
+export async function completeAuthCodeFlow(config, fetchImpl, input, now) {
+    const payload = {
+        grant_type: 'authorization_code',
+        client_id: config.clientId,
+        code: input.code,
+        redirect_uri: input.redirectUri,
+        code_verifier: input.verifier,
+    };
+    if (config.clientSecret)
+        payload.client_secret = config.clientSecret;
+    let res;
+    try {
+        res = await fetchImpl({
+            url: config.tokenEndpoint,
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body: formBody(payload),
+        });
+    }
+    catch (error) {
+        throw new OAuthFlowError('network-error', `Reaching the token endpoint failed: ${describe(error)}`);
+    }
+    if (!res.ok) {
+        throw new OAuthFlowError('token-request-rejected', `Token exchange failed (${await readError(res)}).`, res.status);
+    }
+    return parseTokenResponse(await res.json(), now);
+}
+// ---------------------------------------------------------------------------
+// Device-code flow (RFC 8628)
+// ---------------------------------------------------------------------------
+/** Begin the device-code flow: request a device + user code to display. */
+export async function beginDeviceCodeFlow(config, fetchImpl, now) {
+    assertClientConfigured(config);
+    let res;
+    try {
+        res = await fetchImpl({
+            url: config.deviceAuthorizationEndpoint,
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body: formBody({ client_id: config.clientId, scope: config.scopes.join(' ') }),
+        });
+    }
+    catch (error) {
+        throw new OAuthFlowError('network-error', `Reaching the device endpoint failed: ${describe(error)}`);
+    }
+    if (!res.ok) {
+        throw new OAuthFlowError('token-request-rejected', `Device authorization failed (${await readError(res)}).`, res.status);
+    }
+    const json = (await res.json());
+    const deviceCode = requireString(json.device_code, 'device_code');
+    const userCode = requireString(json.user_code, 'user_code');
+    // Google returns verification_url; the RFC and Microsoft use verification_uri.
+    const verificationUri = typeof json.verification_uri === 'string'
+        ? json.verification_uri
+        : requireString(json.verification_url, 'verification_uri');
+    const expiresIn = typeof json.expires_in === 'number' ? json.expires_in : 900;
+    const interval = typeof json.interval === 'number' ? json.interval : 5;
+    return {
+        deviceCode,
+        userCode,
+        verificationUri,
+        ...(typeof json.verification_uri_complete === 'string'
+            ? { verificationUriComplete: json.verification_uri_complete }
+            : {}),
+        expiresAt: now + expiresIn * 1000,
+        intervalMs: interval * 1000,
+    };
+}
+/**
+ * Poll the token endpoint until the user approves the device code, the code expires,
+ * or the request is denied. Honors authorization_pending (keep polling) and slow_down
+ * (widen the interval) per RFC 8628.
+ */
+export async function pollDeviceCodeFlow(config, fetchImpl, start, clock, sleep) {
+    let intervalMs = start.intervalMs;
+    for (;;) {
+        if (clock() >= start.expiresAt) {
+            throw new OAuthFlowError('device-code-expired', 'The device code expired before it was approved.');
+        }
+        await sleep(intervalMs);
+        const payload = {
+            grant_type: 'urn:ietf:params:oauth:grant-type:device_code',
+            client_id: config.clientId,
+            device_code: start.deviceCode,
+        };
+        if (config.clientSecret)
+            payload.client_secret = config.clientSecret;
+        let res;
+        try {
+            res = await fetchImpl({
+                url: config.tokenEndpoint,
+                method: 'POST',
+                headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+                body: formBody(payload),
+            });
+        }
+        catch (error) {
+            throw new OAuthFlowError('network-error', `Polling the token endpoint failed: ${describe(error)}`);
+        }
+        if (res.ok)
+            return parseTokenResponse(await res.json(), clock());
+        const body = (await res.json().catch(() => ({})));
+        const err = typeof body.error === 'string' ? body.error : `http_${res.status}`;
+        if (err === 'authorization_pending')
+            continue;
+        if (err === 'slow_down') {
+            intervalMs += 5000;
+            continue;
+        }
+        if (err === 'expired_token') {
+            throw new OAuthFlowError('device-code-expired', 'The device code expired before it was approved.');
+        }
+        throw new OAuthFlowError('token-request-rejected', `Device authorization was rejected (${err}).`, res.status);
+    }
+}
+// ---------------------------------------------------------------------------
+// Refresh + revoke
+// ---------------------------------------------------------------------------
+/** Exchange a refresh token for a fresh access token. */
+export async function refreshAccessToken(config, fetchImpl, refreshToken, now) {
+    const payload = {
+        grant_type: 'refresh_token',
+        client_id: config.clientId,
+        refresh_token: refreshToken,
+    };
+    if (config.clientSecret)
+        payload.client_secret = config.clientSecret;
+    let res;
+    try {
+        res = await fetchImpl({
+            url: config.tokenEndpoint,
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded', Accept: 'application/json' },
+            body: formBody(payload),
+        });
+    }
+    catch (error) {
+        throw new OAuthFlowError('network-error', `Reaching the token endpoint failed: ${describe(error)}`);
+    }
+    if (!res.ok) {
+        throw new OAuthFlowError('token-request-rejected', `Token refresh failed (${await readError(res)}).`, res.status);
+    }
+    // Preserve the prior refresh token when the provider omits a new one.
+    return parseTokenResponse(await res.json(), now, refreshToken);
+}
+/**
+ * Revoke a token at the provider (Google). Returns true when the provider confirms.
+ * When the provider has no revocation endpoint (Microsoft), returns false so the
+ * caller knows disconnect is local-only.
+ */
+export async function revokeToken(config, fetchImpl, token) {
+    if (!config.revocationEndpoint)
+        return false;
+    try {
+        const res = await fetchImpl({
+            url: config.revocationEndpoint,
+            method: 'POST',
+            headers: { 'Content-Type': 'application/x-www-form-urlencoded' },
+            body: formBody({ token }),
+        });
+        return res.ok;
+    }
+    catch {
+        // A revocation network failure must not block a local disconnect.
+        return false;
+    }
+}
+// ---------------------------------------------------------------------------
+function requireString(value, field) {
+    if (typeof value !== 'string' || value.length === 0) {
+        throw new OAuthFlowError('token-request-rejected', `Provider response missing ${field}.`);
+    }
+    return value;
+}
+function describe(error) {
+    return error instanceof Error ? error.message : String(error);
+}

package/dist/platform/calendar/oauth-providers.d.ts

@@ -0,0 +1,43 @@
+/**
+ * oauth-providers.ts — the fixed provider profiles for Google Calendar and
+ * Microsoft Outlook (Graph), plus client-config resolution.
+ *
+ * Design (One-Platform Wave 4, A10, per Mike's least-friction rule): the DEFAULT
+ * experience uses a bundled project-level client id (rclone/gh pattern). A native-
+ * app / public-client id is not a secret (RFC 8252), so paired with PKCE no client
+ * secret is needed. Power users MAY override with their own client id (+ secret for
+ * a confidential registration) — surfaced only under an "advanced" affordance, never
+ * as a required step.
+ *
+ * The bundledClientId ships as an honest PLACEHOLDER. Mike registers the two project
+ * apps once and drops the real ids into config defaults; after that every user's flow
+ * is just: connect -> browser opens -> approve -> done. Until then, resolveClientConfig
+ * reports isPlaceholder:true and flows refuse with `client-not-configured` rather than
+ * faking a success.
+ */
+import type { CalendarProviderId, OAuthClientOverrides, OAuthProviderProfile, ResolvedClientConfig } from './oauth-types.js';
+/** Honest placeholders — replaced once the project apps are registered. */
+export declare const GOOGLE_PLACEHOLDER_CLIENT_ID = "REPLACE_WITH_PROJECT_GOOGLE_CLIENT_ID.apps.googleusercontent.com";
+export declare const MICROSOFT_PLACEHOLDER_CLIENT_ID = "REPLACE_WITH_PROJECT_MICROSOFT_CLIENT_ID";
+/** Google Calendar read scope and read/write events scope. Read-write is the default
+ *  so event creation works; a user may narrow to read-only via overrides. */
+export declare const GOOGLE_SCOPES_DEFAULT: readonly ["https://www.googleapis.com/auth/calendar.readonly", "https://www.googleapis.com/auth/calendar.events"];
+/** Microsoft Graph read/write calendar scope (+ offline_access for a refresh token). */
+export declare const MICROSOFT_SCOPES_DEFAULT: readonly ["offline_access", "Calendars.ReadWrite"];
+export declare const GOOGLE_PROFILE: OAuthProviderProfile;
+export declare const MICROSOFT_PROFILE: OAuthProviderProfile;
+/** Look up a provider profile. */
+export declare function providerProfile(provider: CalendarProviderId): OAuthProviderProfile;
+/**
+ * Merge a profile with a user's optional overrides into the config a flow runs with.
+ * A bundled profile whose id is still the placeholder resolves isPlaceholder:true
+ * UNLESS the user supplied their own clientId.
+ */
+export declare function resolveClientConfig(profile: OAuthProviderProfile, overrides?: OAuthClientOverrides): ResolvedClientConfig;
+/**
+ * The exact provider-console steps a user (or Mike, registering the project apps)
+ * follows. Surfaced verbatim by the wizard's "advanced" help and copied into the
+ * module docs. Kept as data so the wizard and docs never drift.
+ */
+export declare const PROVIDER_SETUP_STEPS: Readonly<Record<CalendarProviderId, readonly string[]>>;
+//# sourceMappingURL=oauth-providers.d.ts.map

package/dist/platform/calendar/oauth-providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-providers.d.ts","sourceRoot":"","sources":["../../../src/platform/calendar/oauth-providers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,OAAO,KAAK,EACV,kBAAkB,EAClB,oBAAoB,EACpB,oBAAoB,EACpB,oBAAoB,EACrB,MAAM,kBAAkB,CAAC;AAE1B,2EAA2E;AAC3E,eAAO,MAAM,4BAA4B,qEAC2B,CAAC;AACrE,eAAO,MAAM,+BAA+B,6CACA,CAAC;AAE7C;6EAC6E;AAC7E,eAAO,MAAM,qBAAqB,mHAGxB,CAAC;AAEX,wFAAwF;AACxF,eAAO,MAAM,wBAAwB,oDAG3B,CAAC;AAEX,eAAO,MAAM,cAAc,EAAE,oBAc5B,CAAC;AAEF,eAAO,MAAM,iBAAiB,EAAE,oBAY/B,CAAC;AAOF,kCAAkC;AAClC,wBAAgB,eAAe,CAAC,QAAQ,EAAE,kBAAkB,GAAG,oBAAoB,CAElF;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CACjC,OAAO,EAAE,oBAAoB,EAC7B,SAAS,CAAC,EAAE,oBAAoB,GAC/B,oBAAoB,CAwBtB;AAED;;;;GAIG;AACH,eAAO,MAAM,oBAAoB,EAAE,QAAQ,CAAC,MAAM,CAAC,kBAAkB,EAAE,SAAS,MAAM,EAAE,CAAC,CAiBxF,CAAC"}

package/dist/platform/calendar/oauth-providers.js

@@ -0,0 +1,120 @@
+/**
+ * oauth-providers.ts — the fixed provider profiles for Google Calendar and
+ * Microsoft Outlook (Graph), plus client-config resolution.
+ *
+ * Design (One-Platform Wave 4, A10, per Mike's least-friction rule): the DEFAULT
+ * experience uses a bundled project-level client id (rclone/gh pattern). A native-
+ * app / public-client id is not a secret (RFC 8252), so paired with PKCE no client
+ * secret is needed. Power users MAY override with their own client id (+ secret for
+ * a confidential registration) — surfaced only under an "advanced" affordance, never
+ * as a required step.
+ *
+ * The bundledClientId ships as an honest PLACEHOLDER. Mike registers the two project
+ * apps once and drops the real ids into config defaults; after that every user's flow
+ * is just: connect -> browser opens -> approve -> done. Until then, resolveClientConfig
+ * reports isPlaceholder:true and flows refuse with `client-not-configured` rather than
+ * faking a success.
+ */
+/** Honest placeholders — replaced once the project apps are registered. */
+export const GOOGLE_PLACEHOLDER_CLIENT_ID = 'REPLACE_WITH_PROJECT_GOOGLE_CLIENT_ID.apps.googleusercontent.com';
+export const MICROSOFT_PLACEHOLDER_CLIENT_ID = 'REPLACE_WITH_PROJECT_MICROSOFT_CLIENT_ID';
+/** Google Calendar read scope and read/write events scope. Read-write is the default
+ *  so event creation works; a user may narrow to read-only via overrides. */
+export const GOOGLE_SCOPES_DEFAULT = [
+    'https://www.googleapis.com/auth/calendar.readonly',
+    'https://www.googleapis.com/auth/calendar.events',
+];
+/** Microsoft Graph read/write calendar scope (+ offline_access for a refresh token). */
+export const MICROSOFT_SCOPES_DEFAULT = [
+    'offline_access',
+    'Calendars.ReadWrite',
+];
+export const GOOGLE_PROFILE = {
+    provider: 'google',
+    displayName: 'Google Calendar',
+    authorizationEndpoint: 'https://accounts.google.com/o/oauth2/v2/auth',
+    tokenEndpoint: 'https://oauth2.googleapis.com/token',
+    deviceAuthorizationEndpoint: 'https://oauth2.googleapis.com/device/code',
+    revocationEndpoint: 'https://oauth2.googleapis.com/revoke',
+    apiBaseUrl: 'https://www.googleapis.com/calendar/v3',
+    defaultScopes: GOOGLE_SCOPES_DEFAULT,
+    bundledClientId: GOOGLE_PLACEHOLDER_CLIENT_ID,
+    placeholderClientId: GOOGLE_PLACEHOLDER_CLIENT_ID,
+    // access_type=offline + prompt=consent so Google returns a refresh token on the
+    // first authorization and re-issues one on re-consent.
+    extraAuthParams: { access_type: 'offline', prompt: 'consent' },
+};
+export const MICROSOFT_PROFILE = {
+    provider: 'microsoft',
+    displayName: 'Microsoft Outlook',
+    // 'common' lets both personal and work/school accounts authenticate.
+    authorizationEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/authorize',
+    tokenEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/token',
+    deviceAuthorizationEndpoint: 'https://login.microsoftonline.com/common/oauth2/v2.0/devicecode',
+    // Microsoft has no OAuth revocation endpoint; disconnect is local token deletion.
+    apiBaseUrl: 'https://graph.microsoft.com/v1.0',
+    defaultScopes: MICROSOFT_SCOPES_DEFAULT,
+    bundledClientId: MICROSOFT_PLACEHOLDER_CLIENT_ID,
+    placeholderClientId: MICROSOFT_PLACEHOLDER_CLIENT_ID,
+};
+const PROFILES = {
+    google: GOOGLE_PROFILE,
+    microsoft: MICROSOFT_PROFILE,
+};
+/** Look up a provider profile. */
+export function providerProfile(provider) {
+    return PROFILES[provider];
+}
+/**
+ * Merge a profile with a user's optional overrides into the config a flow runs with.
+ * A bundled profile whose id is still the placeholder resolves isPlaceholder:true
+ * UNLESS the user supplied their own clientId.
+ */
+export function resolveClientConfig(profile, overrides) {
+    const overrodeClientId = typeof overrides?.clientId === 'string' && overrides.clientId.trim().length > 0;
+    const clientId = overrodeClientId ? overrides.clientId.trim() : profile.bundledClientId;
+    const usingBundledDefault = !overrodeClientId;
+    const isPlaceholder = usingBundledDefault && clientId === profile.placeholderClientId;
+    const scopes = overrides?.scopes && overrides.scopes.length > 0 ? overrides.scopes : profile.defaultScopes;
+    return {
+        provider: profile.provider,
+        clientId,
+        ...(overrides?.clientSecret && overrides.clientSecret.length > 0
+            ? { clientSecret: overrides.clientSecret }
+            : {}),
+        scopes,
+        authorizationEndpoint: profile.authorizationEndpoint,
+        tokenEndpoint: profile.tokenEndpoint,
+        deviceAuthorizationEndpoint: profile.deviceAuthorizationEndpoint,
+        ...(profile.revocationEndpoint ? { revocationEndpoint: profile.revocationEndpoint } : {}),
+        apiBaseUrl: profile.apiBaseUrl,
+        ...(profile.extraAuthParams ? { extraAuthParams: profile.extraAuthParams } : {}),
+        ...(overrides?.redirectHost ? { redirectHost: overrides.redirectHost } : {}),
+        ...(typeof overrides?.redirectPort === 'number' ? { redirectPort: overrides.redirectPort } : {}),
+        usingBundledDefault,
+        isPlaceholder,
+    };
+}
+/**
+ * The exact provider-console steps a user (or Mike, registering the project apps)
+ * follows. Surfaced verbatim by the wizard's "advanced" help and copied into the
+ * module docs. Kept as data so the wizard and docs never drift.
+ */
+export const PROVIDER_SETUP_STEPS = {
+    google: [
+        'Open the Google Cloud Console (console.cloud.google.com) and select or create a project.',
+        'APIs & Services -> Library -> enable "Google Calendar API".',
+        'APIs & Services -> OAuth consent screen -> configure (External is fine for personal use); add your Google account under Test users while the app is unverified.',
+        'APIs & Services -> Credentials -> Create Credentials -> OAuth client ID -> Application type "Desktop app".',
+        'Copy the generated Client ID. A Desktop-app client needs NO client secret with PKCE; leave the secret field blank unless you deliberately use a Web-app client.',
+        'Paste the Client ID into the wizard under "advanced", or (project owner) drop it into the config default calendar.google.clientId.',
+    ],
+    microsoft: [
+        'Open the Azure portal (portal.azure.com) -> Microsoft Entra ID -> App registrations -> New registration.',
+        'Name the app; under "Supported account types" pick "Accounts in any organizational directory and personal Microsoft accounts" for the broadest reach.',
+        'Under "Redirect URI" add a "Mobile and desktop applications" platform and the entry http://localhost (the loopback flow supplies its own 127.0.0.1 port).',
+        'Registration -> Authentication -> enable "Allow public client flows" = Yes (this is the public-client / device-code property; no client secret is needed).',
+        'Registration -> API permissions -> Add a permission -> Microsoft Graph -> Delegated -> add Calendars.ReadWrite and offline_access.',
+        'Copy the "Application (client) ID". Paste it into the wizard under "advanced", or (project owner) drop it into the config default calendar.microsoft.clientId.',
+    ],
+};