@pellux/goodvibes-sdk 0.38.0 → 1.1.0

package/dist/platform/calendar/oauth-token-store.d.ts

@@ -0,0 +1,72 @@
+/**
+ * oauth-token-store.ts — token persistence + honest lifecycle over the injected
+ * secret store. Tokens (access + refresh) live ONLY in the secret store, never in
+ * plain config and never echoed. The store computes an honest connection state from
+ * the stored set + the clock, auto-refreshes when the access token is due, and — when
+ * a refresh fails — records a durable `reconnect-needed` marker so every later read is
+ * honest about the account being broken until the user reconnects.
+ */
+import type { CalendarProviderId, Clock, ConnectedAccount, ConnectionState, HttpFetch, ResolvedClientConfig, SecretStoreSlice, StoredTokenSet } from './oauth-types.js';
+export interface CalendarTokenStoreOptions {
+    readonly secrets: SecretStoreSlice;
+    readonly clock?: Clock;
+    /** How long before expiry a token counts as due for refresh. */
+    readonly refreshLeewayMs?: number;
+}
+/** A refresh failure the caller turns into a "reconnect needed" surface. */
+export declare class TokenRefreshError extends Error {
+    readonly provider: CalendarProviderId;
+    constructor(provider: CalendarProviderId, message: string);
+}
+export declare class CalendarTokenStore {
+    private readonly secrets;
+    private readonly clock;
+    private readonly leewayMs;
+    /**
+     * In-instance single-flight dedup for concurrent refreshes of the same provider.
+     * Providers that rotate refresh tokens (Microsoft) invalidate the prior refresh
+     * token the moment one refresh succeeds — a second concurrent call that still
+     * holds the OLD refresh token would otherwise lose the race with invalid_grant
+     * and stamp reconnect-needed over a perfectly working account. Every concurrent
+     * caller for a given provider instead awaits the SAME in-flight refresh.
+     */
+    private readonly inflightRefresh;
+    constructor(options: CalendarTokenStoreOptions);
+    /** Persist a fresh token set + account metadata; clears any reconnect marker. */
+    save(provider: CalendarProviderId, tokens: StoredTokenSet, account: ConnectedAccount): Promise<void>;
+    /** Read the stored token set for a provider, or null when disconnected. */
+    load(provider: CalendarProviderId): Promise<StoredTokenSet | null>;
+    /** Read the account metadata for a provider, or null. */
+    loadAccount(provider: CalendarProviderId): Promise<ConnectedAccount | null>;
+    /** List every connected account across providers. */
+    listAccounts(): Promise<ConnectedAccount[]>;
+    /** The honest connection state, from the marker + stored set + clock. */
+    connectionState(provider: CalendarProviderId): Promise<ConnectionState>;
+    /**
+     * Return a usable access token, refreshing first when it is due. On a refresh
+     * failure this records a durable reconnect-needed marker and throws
+     * TokenRefreshError — never returns a stale/invalid token as if it were good.
+     */
+    getFreshAccessToken(provider: CalendarProviderId, config: ResolvedClientConfig, fetchImpl: HttpFetch): Promise<string>;
+    private performRefresh;
+    /**
+     * Disconnect a provider: revoke the token at the provider when possible, then
+     * delete every stored key. Returns whether the provider-side revocation succeeded
+     * (false for providers without a revocation endpoint — disconnect is still local).
+     */
+    disconnect(provider: CalendarProviderId, config: ResolvedClientConfig, fetchImpl: HttpFetch): Promise<{
+        readonly revokedRemotely: boolean;
+    }>;
+    /**
+     * Stamp the durable reconnect-needed marker — UNLESS a valid (non-expired) token
+     * set already exists. A refresh can fail here while a concurrent winner (this
+     * instance's own single-flight already prevents an in-process race, but a
+     * separate process/instance sharing the same secret store is not covered by
+     * that) has already stored a fresh, working token set for the same provider.
+     * Re-reading state immediately before writing the marker means a genuinely
+     * working account is never overwritten with a false "reconnect needed".
+     */
+    private markReconnectNeeded;
+    private syntheticAccount;
+}
+//# sourceMappingURL=oauth-token-store.d.ts.map

package/dist/platform/calendar/oauth-token-store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-token-store.d.ts","sourceRoot":"","sources":["../../../src/platform/calendar/oauth-token-store.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAGH,OAAO,KAAK,EACV,kBAAkB,EAClB,KAAK,EACL,gBAAgB,EAChB,eAAe,EACf,SAAS,EACT,oBAAoB,EACpB,gBAAgB,EAChB,cAAc,EACf,MAAM,kBAAkB,CAAC;AAgB1B,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,KAAK,CAAC,EAAE,KAAK,CAAC;IACvB,gEAAgE;IAChE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAC;CACnC;AAED,4EAA4E;AAC5E,qBAAa,iBAAkB,SAAQ,KAAK;IAC1C,QAAQ,CAAC,QAAQ,EAAE,kBAAkB,CAAC;gBAC1B,QAAQ,EAAE,kBAAkB,EAAE,OAAO,EAAE,MAAM;CAK1D;AAED,qBAAa,kBAAkB;IAC7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAmB;IAC3C,OAAO,CAAC,QAAQ,CAAC,KAAK,CAAQ;IAC9B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC;;;;;;;OAOG;IACH,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAkD;gBAEtE,OAAO,EAAE,yBAAyB;IAM9C,iFAAiF;IAC3E,IAAI,CAAC,QAAQ,EAAE,kBAAkB,EAAE,MAAM,EAAE,cAAc,EAAE,OAAO,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;IAM1G,2EAA2E;IACrE,IAAI,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,cAAc,GAAG,IAAI,CAAC;IAUxE,yDAAyD;IACnD,WAAW,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAUjF,qDAAqD;IAC/C,YAAY,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC;IASjD,yEAAyE;IACnE,eAAe,CAAC,QAAQ,EAAE,kBAAkB,GAAG,OAAO,CAAC,eAAe,CAAC;IAS7E;;;;OAIG;IACG,mBAAmB,CACvB,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC,MAAM,CAAC;YAuBJ,cAAc;IAmB5B;;;;OAIG;IACG,UAAU,CACd,QAAQ,EAAE,kBAAkB,EAC5B,MAAM,EAAE,oBAAoB,EAC5B,SAAS,EAAE,SAAS,GACnB,OAAO,CAAC;QAAE,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAA;KAAE,CAAC;IAYjD;;;;;;;;OAQG;YACW,mBAAmB;IASjC,OAAO,CAAC,gBAAgB;CASzB"}

package/dist/platform/calendar/oauth-token-store.js

@@ -0,0 +1,189 @@
+/**
+ * oauth-token-store.ts — token persistence + honest lifecycle over the injected
+ * secret store. Tokens (access + refresh) live ONLY in the secret store, never in
+ * plain config and never echoed. The store computes an honest connection state from
+ * the stored set + the clock, auto-refreshes when the access token is due, and — when
+ * a refresh fails — records a durable `reconnect-needed` marker so every later read is
+ * honest about the account being broken until the user reconnects.
+ */
+import { OAuthFlowError, refreshAccessToken, revokeToken } from './oauth-flow.js';
+const DEFAULT_REFRESH_LEEWAY_MS = 60_000;
+function tokenKey(provider) {
+    return `GOODVIBES_CALENDAR_${provider.toUpperCase()}_TOKENS`;
+}
+function accountKey(provider) {
+    return `GOODVIBES_CALENDAR_${provider.toUpperCase()}_ACCOUNT`;
+}
+function statusKey(provider) {
+    return `GOODVIBES_CALENDAR_${provider.toUpperCase()}_STATUS`;
+}
+const ALL_PROVIDERS = ['google', 'microsoft'];
+/** A refresh failure the caller turns into a "reconnect needed" surface. */
+export class TokenRefreshError extends Error {
+    provider;
+    constructor(provider, message) {
+        super(message);
+        this.name = 'TokenRefreshError';
+        this.provider = provider;
+    }
+}
+export class CalendarTokenStore {
+    secrets;
+    clock;
+    leewayMs;
+    /**
+     * In-instance single-flight dedup for concurrent refreshes of the same provider.
+     * Providers that rotate refresh tokens (Microsoft) invalidate the prior refresh
+     * token the moment one refresh succeeds — a second concurrent call that still
+     * holds the OLD refresh token would otherwise lose the race with invalid_grant
+     * and stamp reconnect-needed over a perfectly working account. Every concurrent
+     * caller for a given provider instead awaits the SAME in-flight refresh.
+     */
+    inflightRefresh = new Map();
+    constructor(options) {
+        this.secrets = options.secrets;
+        this.clock = options.clock ?? (() => Date.now());
+        this.leewayMs = options.refreshLeewayMs ?? DEFAULT_REFRESH_LEEWAY_MS;
+    }
+    /** Persist a fresh token set + account metadata; clears any reconnect marker. */
+    async save(provider, tokens, account) {
+        await this.secrets.set(tokenKey(provider), JSON.stringify(tokens));
+        await this.secrets.set(accountKey(provider), JSON.stringify(account));
+        await this.secrets.delete(statusKey(provider));
+    }
+    /** Read the stored token set for a provider, or null when disconnected. */
+    async load(provider) {
+        const raw = await this.secrets.get(tokenKey(provider));
+        if (!raw)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** Read the account metadata for a provider, or null. */
+    async loadAccount(provider) {
+        const raw = await this.secrets.get(accountKey(provider));
+        if (!raw)
+            return null;
+        try {
+            return JSON.parse(raw);
+        }
+        catch {
+            return null;
+        }
+    }
+    /** List every connected account across providers. */
+    async listAccounts() {
+        const out = [];
+        for (const provider of ALL_PROVIDERS) {
+            const account = await this.loadAccount(provider);
+            if (account)
+                out.push(account);
+        }
+        return out;
+    }
+    /** The honest connection state, from the marker + stored set + clock. */
+    async connectionState(provider) {
+        if (await this.secrets.get(statusKey(provider)))
+            return 'reconnect-needed';
+        const tokens = await this.load(provider);
+        if (!tokens)
+            return 'disconnected';
+        if (typeof tokens.expiresAt !== 'number')
+            return 'connected';
+        if (this.clock() < tokens.expiresAt - this.leewayMs)
+            return 'connected';
+        return tokens.refreshToken ? 'refresh-due' : 'reconnect-needed';
+    }
+    /**
+     * Return a usable access token, refreshing first when it is due. On a refresh
+     * failure this records a durable reconnect-needed marker and throws
+     * TokenRefreshError — never returns a stale/invalid token as if it were good.
+     */
+    async getFreshAccessToken(provider, config, fetchImpl) {
+        const tokens = await this.load(provider);
+        if (!tokens)
+            throw new TokenRefreshError(provider, `No ${provider} account is connected.`);
+        const due = typeof tokens.expiresAt === 'number' && this.clock() >= tokens.expiresAt - this.leewayMs;
+        if (!due)
+            return tokens.accessToken;
+        if (!tokens.refreshToken) {
+            await this.markReconnectNeeded(provider);
+            throw new TokenRefreshError(provider, `The ${provider} access token expired and no refresh token is stored.`);
+        }
+        // Single-flight: a refresh already in progress for this provider serves every
+        // concurrent caller instead of each racing the provider with the same (possibly
+        // about-to-be-rotated) refresh token.
+        const existing = this.inflightRefresh.get(provider);
+        if (existing)
+            return existing;
+        const refreshToken = tokens.refreshToken;
+        const inFlight = this.performRefresh(provider, config, fetchImpl, refreshToken)
+            .finally(() => {
+            if (this.inflightRefresh.get(provider) === inFlight)
+                this.inflightRefresh.delete(provider);
+        });
+        this.inflightRefresh.set(provider, inFlight);
+        return inFlight;
+    }
+    async performRefresh(provider, config, fetchImpl, refreshToken) {
+        let refreshed;
+        try {
+            refreshed = await refreshAccessToken(config, fetchImpl, refreshToken, this.clock());
+        }
+        catch (error) {
+            await this.markReconnectNeeded(provider);
+            const detail = error instanceof OAuthFlowError ? error.message : String(error);
+            throw new TokenRefreshError(provider, `Refreshing the ${provider} token failed: ${detail}`);
+        }
+        const account = (await this.loadAccount(provider)) ?? this.syntheticAccount(provider, refreshed);
+        await this.save(provider, refreshed, account);
+        return refreshed.accessToken;
+    }
+    /**
+     * Disconnect a provider: revoke the token at the provider when possible, then
+     * delete every stored key. Returns whether the provider-side revocation succeeded
+     * (false for providers without a revocation endpoint — disconnect is still local).
+     */
+    async disconnect(provider, config, fetchImpl) {
+        const tokens = await this.load(provider);
+        let revokedRemotely = false;
+        if (tokens) {
+            revokedRemotely = await revokeToken(config, fetchImpl, tokens.refreshToken ?? tokens.accessToken);
+        }
+        await this.secrets.delete(tokenKey(provider));
+        await this.secrets.delete(accountKey(provider));
+        await this.secrets.delete(statusKey(provider));
+        return { revokedRemotely };
+    }
+    /**
+     * Stamp the durable reconnect-needed marker — UNLESS a valid (non-expired) token
+     * set already exists. A refresh can fail here while a concurrent winner (this
+     * instance's own single-flight already prevents an in-process race, but a
+     * separate process/instance sharing the same secret store is not covered by
+     * that) has already stored a fresh, working token set for the same provider.
+     * Re-reading state immediately before writing the marker means a genuinely
+     * working account is never overwritten with a false "reconnect needed".
+     */
+    async markReconnectNeeded(provider) {
+        const current = await this.load(provider);
+        if (current) {
+            const stillValid = typeof current.expiresAt !== 'number' || this.clock() < current.expiresAt - this.leewayMs;
+            if (stillValid)
+                return;
+        }
+        await this.secrets.set(statusKey(provider), 'reconnect-needed');
+    }
+    syntheticAccount(provider, tokens) {
+        return {
+            provider,
+            accountId: provider,
+            label: provider === 'google' ? 'Google Calendar' : 'Microsoft Outlook',
+            scopes: tokens.scopes ?? [],
+            connectedAt: tokens.obtainedAt,
+        };
+    }
+}

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

@@ -0,0 +1,274 @@
+/**
+ * oauth-types.ts — the shared type surface for the calendar OAuth + API connector
+ * layer (see CHANGELOG 1.0.0, A10). Sits alongside A9's .ics reader/subscription
+ * store in the same module: A9 owns file/feed reading; this half owns authenticated
+ * provider connectivity (Google Calendar API v3, Microsoft Graph) over OAuth 2.0.
+ *
+ * Pure data shapes only — no fs, no network, no process globals. The network is an
+ * INJECTED boundary (HttpFetch); the loopback redirect capture is an INJECTED
+ * boundary (LoopbackWaiter); token persistence is an INJECTED secret store slice.
+ * Tests supply fakes for all three, so nothing here ever reaches a real network,
+ * a real port, or a real keychain.
+ *
+ * Honesty contract (see docs/decisions/2026-07-06-calendar-oauth-connector-sdk.md):
+ *  - a token whose refresh fails is NEVER silently treated as valid; it surfaces as
+ *    `connection-state: 'reconnect-needed'` naming the reason.
+ *  - a 403 that names a missing scope surfaces as `insufficient-scope` naming the
+ *    exact scope, not a generic failure.
+ *  - the bundled project client id is an honest placeholder until Mike registers the
+ *    project apps; a flow attempted against the placeholder reports
+ *    `client-not-configured`, never a fake success.
+ */
+import type { CalendarEvent, EventDateTime } from './types.js';
+export type { Clock } from './types.js';
+/** Which authenticated calendar provider a connection speaks to. */
+export type CalendarProviderId = 'google' | 'microsoft';
+/** The label recorded on every event so a merged view can say where it came from. */
+export type CalendarSource = 'google-api' | 'microsoft-graph' | 'ics-feed' | 'local';
+/**
+ * A provider profile: the fixed OAuth + API endpoints and defaults for one provider.
+ * Everything a user does NOT supply (endpoints, default scopes, the bundled project
+ * client id) lives here; what the user CAN supply (their own client id/secret,
+ * scope overrides) arrives as OAuthClientOverrides and is merged in at resolve time.
+ */
+export interface OAuthProviderProfile {
+    readonly provider: CalendarProviderId;
+    /** Human label, e.g. 'Google Calendar' / 'Microsoft Outlook'. */
+    readonly displayName: string;
+    readonly authorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    /** Device-authorization endpoint; both providers support the device-code grant. */
+    readonly deviceAuthorizationEndpoint: string;
+    /** Token-revocation endpoint, when the provider offers one (Google does; MS does not). */
+    readonly revocationEndpoint?: string;
+    /** The API base the calendar client talks to after auth. */
+    readonly apiBaseUrl: string;
+    /** Default scopes when the user does not override them. */
+    readonly defaultScopes: readonly string[];
+    /**
+     * The project-level ("bundled") client id shipped in config defaults — the
+     * rclone/gh pattern. Native-app client ids are not secrets (RFC 8252); paired
+     * with PKCE no client secret is needed for the installed-app / public-client
+     * profile. Ships as an honest PLACEHOLDER until Mike registers the project apps.
+     */
+    readonly bundledClientId: string;
+    /**
+     * The literal placeholder value bundledClientId holds before real registration.
+     * When the resolved client id still equals this, the flow reports
+     * `client-not-configured` instead of attempting a doomed round-trip.
+     */
+    readonly placeholderClientId: string;
+    /** Extra fixed authorization-request params (e.g. Google's access_type=offline). */
+    readonly extraAuthParams?: Readonly<Record<string, string>>;
+}
+/** What a user MAY override — never required; surfaced only under "advanced". */
+export interface OAuthClientOverrides {
+    /** A user's own registered client id (confidential- or public-client). */
+    readonly clientId?: string;
+    /**
+     * A user's own client secret, for a confidential-client registration. Absent for
+     * the default public native-app profile (PKCE, no secret). Secret-stored, never
+     * echoed.
+     */
+    readonly clientSecret?: string;
+    /** Scope override; when absent the profile's defaultScopes are used. */
+    readonly scopes?: readonly string[];
+    /** Loopback redirect host/port override for the auth-code flow. */
+    readonly redirectHost?: string;
+    readonly redirectPort?: number;
+}
+/** The fully-resolved client config a flow actually runs with. */
+export interface ResolvedClientConfig {
+    readonly provider: CalendarProviderId;
+    readonly clientId: string;
+    readonly clientSecret?: string;
+    readonly scopes: readonly string[];
+    readonly authorizationEndpoint: string;
+    readonly tokenEndpoint: string;
+    readonly deviceAuthorizationEndpoint: string;
+    readonly revocationEndpoint?: string;
+    readonly apiBaseUrl: string;
+    readonly extraAuthParams?: Readonly<Record<string, string>>;
+    readonly redirectHost?: string;
+    readonly redirectPort?: number;
+    /** True when clientId came from the bundled project default, not a user override. */
+    readonly usingBundledDefault: boolean;
+    /**
+     * True when the resolved clientId is still the honest placeholder — i.e. neither
+     * Mike's project registration nor a user override supplied a real id. A flow must
+     * refuse with `client-not-configured` in this state.
+     */
+    readonly isPlaceholder: boolean;
+}
+/** A minimal HTTP response shape the connector reads. */
+export interface HttpResponse {
+    readonly status: number;
+    readonly ok: boolean;
+    /** Response header lookup, case-insensitive by the fetch impl's contract. */
+    header(name: string): string | null;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}
+/** A single outbound HTTP request the connector issues. */
+export interface HttpRequest {
+    readonly url: string;
+    readonly method: 'GET' | 'POST' | 'DELETE' | 'PATCH';
+    readonly headers?: Readonly<Record<string, string>>;
+    readonly body?: string;
+}
+/** Injected network boundary. Tests supply a fake server behind this. */
+export type HttpFetch = (req: HttpRequest) => Promise<HttpResponse>;
+/**
+ * Injected loopback-redirect capture for the authorization-code flow. The real
+ * implementation binds 127.0.0.1 and waits for the browser callback; tests supply a
+ * fake that returns a canned code/state without any port.
+ */
+export interface LoopbackWaiter {
+    /** The redirect_uri the listener is bound to (http://127.0.0.1:<port>/<path>). */
+    readonly redirectUri: string;
+    /** Resolves with the authorization code once the browser hits the redirect. */
+    waitForCode(): Promise<{
+        readonly code: string;
+        readonly state: string;
+    }>;
+    close(): void;
+}
+/** Factory for a LoopbackWaiter bound to an expected state. Injected. */
+export type LoopbackListenerFactory = (input: {
+    readonly expectedState: string;
+    readonly host?: string;
+    readonly port?: number;
+    readonly timeoutMs?: number;
+}) => Promise<LoopbackWaiter>;
+/**
+ * The narrow secret-store slice the token store needs. Matches the SDK
+ * SecretsManager surface (`Pick<SecretsManager, 'get' | 'set' | 'delete'>`), so a
+ * caller passes the real manager and tests pass a Map-backed fake.
+ */
+export interface SecretStoreSlice {
+    get(key: string): Promise<string | null>;
+    set(key: string, value: string): Promise<void>;
+    delete(key: string): Promise<void>;
+}
+/** A stored token set for one connected account. Persisted via the secret store. */
+export interface StoredTokenSet {
+    readonly accessToken: string;
+    readonly refreshToken?: string;
+    readonly tokenType: string;
+    /**
+     * Epoch ms the access token expires. `parseTokenResponse` (oauth-flow.ts) always
+     * sets this — coercing a numeric-string `expires_in`, or falling back to a
+     * conservative default when the provider omits it or sends something unparsable —
+     * so a token set produced by this build's flows never reads as "never expires".
+     * Still optional at the type level for token sets constructed directly (e.g. tests,
+     * or a caller building one by hand) rather than through `parseTokenResponse`.
+     */
+    readonly expiresAt?: number;
+    /** The scopes actually granted (from the token response), when stated. */
+    readonly scopes?: readonly string[];
+    /** Epoch ms this set was last written. */
+    readonly obtainedAt: number;
+}
+/** The honest live state of a connection, computed from its stored token set. */
+export type ConnectionState = 
+/** Access token present and not past expiry (minus leeway). */
+'connected'
+/** Access token expired but a refresh token is present — a refresh will be tried. */
+ | 'refresh-due'
+/** Refresh was attempted and failed; the user must reconnect. */
+ | 'reconnect-needed'
+/** No token stored for this account. */
+ | 'disconnected';
+/** Why a flow could not even start or complete, named honestly. */
+export type FlowFailureReason = 
+/** The resolved client id is still the placeholder (project app not registered
+ *  and no user override). */
+'client-not-configured'
+/** The provider rejected the token request (bad code, expired device code, etc.). */
+ | 'token-request-rejected'
+/** The loopback redirect timed out waiting for the browser. */
+ | 'redirect-timeout'
+/** The device-code authorization was declined or expired before approval. */
+ | 'device-code-expired'
+/** A network-layer failure reaching the provider. */
+ | 'network-error';
+/** The outcome of beginning an authorization-code flow. */
+export interface AuthCodeFlowStart {
+    readonly authorizationUrl: string;
+    readonly state: string;
+    readonly verifier: string;
+    readonly redirectUri: string;
+}
+/** A device-code flow's user-facing step: show these, then poll. */
+export interface DeviceCodeFlowStart {
+    readonly deviceCode: string;
+    readonly userCode: string;
+    readonly verificationUri: string;
+    /** Present when the provider returns a pre-filled verification URL. */
+    readonly verificationUriComplete?: string;
+    readonly expiresAt: number;
+    readonly intervalMs: number;
+}
+/** A degraded API state, each variant naming exactly what went wrong. */
+export type ApiDegradedState = {
+    readonly kind: 'reconnect-needed';
+    readonly detail: string;
+} | {
+    readonly kind: 'insufficient-scope';
+    readonly missingScope: string;
+    readonly detail: string;
+} | {
+    readonly kind: 'rate-limited';
+    readonly retryAfterMs: number;
+    readonly detail: string;
+} | {
+    readonly kind: 'network-error';
+    readonly detail: string;
+} | {
+    readonly kind: 'provider-error';
+    readonly status: number;
+    readonly detail: string;
+};
+/**
+ * The one merged event model every source normalizes into. It is A9's CalendarEvent
+ * plus provenance: a source label and the provider ids needed to write back or
+ * de-duplicate. ICS/local events set source and omit the api-only ids.
+ */
+export interface MergedCalendarEvent extends CalendarEvent {
+    readonly source: CalendarSource;
+    /** The provider's own event id (Google eventId / Graph id), when from an API. */
+    readonly sourceEventId?: string;
+    /** The provider calendar this event belongs to, when from an API. */
+    readonly calendarId?: string;
+    /** A display label for the owning calendar/account, for source-labeled views. */
+    readonly calendarLabel?: string;
+}
+/** One connected calendar as listed from a provider (calendarList / me/calendars). */
+export interface ProviderCalendar {
+    readonly id: string;
+    readonly name: string;
+    readonly provider: CalendarProviderId;
+    /** True for the account's primary calendar, when the provider marks one. */
+    readonly primary?: boolean;
+    /** True when the connected scopes allow creating events on this calendar. */
+    readonly canWrite: boolean;
+}
+/** A new event to create through a provider, in the shared shape. */
+export interface NewCalendarEvent {
+    readonly summary: string;
+    readonly start: EventDateTime;
+    readonly end?: EventDateTime;
+    readonly location?: string;
+    readonly description?: string;
+}
+/** A connected account record (metadata; tokens live in the secret store). */
+export interface ConnectedAccount {
+    readonly provider: CalendarProviderId;
+    /** A stable local id for this account (provider + a discriminator). */
+    readonly accountId: string;
+    /** A human label (the account email/UPN when known, else the provider name). */
+    readonly label: string;
+    readonly scopes: readonly string[];
+    readonly connectedAt: number;
+}
+//# sourceMappingURL=oauth-types.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"oauth-types.d.ts","sourceRoot":"","sources":["../../../src/platform/calendar/oauth-types.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,22 @@
+/**
+ * oauth-types.ts — the shared type surface for the calendar OAuth + API connector
+ * layer (see CHANGELOG 1.0.0, A10). Sits alongside A9's .ics reader/subscription
+ * store in the same module: A9 owns file/feed reading; this half owns authenticated
+ * provider connectivity (Google Calendar API v3, Microsoft Graph) over OAuth 2.0.
+ *
+ * Pure data shapes only — no fs, no network, no process globals. The network is an
+ * INJECTED boundary (HttpFetch); the loopback redirect capture is an INJECTED
+ * boundary (LoopbackWaiter); token persistence is an INJECTED secret store slice.
+ * Tests supply fakes for all three, so nothing here ever reaches a real network,
+ * a real port, or a real keychain.
+ *
+ * Honesty contract (see docs/decisions/2026-07-06-calendar-oauth-connector-sdk.md):
+ *  - a token whose refresh fails is NEVER silently treated as valid; it surfaces as
+ *    `connection-state: 'reconnect-needed'` naming the reason.
+ *  - a 403 that names a missing scope surfaces as `insufficient-scope` naming the
+ *    exact scope, not a generic failure.
+ *  - the bundled project client id is an honest placeholder until Mike registers the
+ *    project apps; a flow attempted against the placeholder reports
+ *    `client-not-configured`, never a fake success.
+ */
+export {};

package/dist/platform/calendar/rrule.d.ts

@@ -0,0 +1,39 @@
+/**
+ * rrule.ts — a pure RRULE reader for an honest, deliberately-bounded subset.
+ *
+ * The honesty rule (see the decision record): an event's recurrence is either
+ * FULLY and correctly expanded, or NOT expanded at all with an explicit reason.
+ * We never emit occurrences from a rule we do not completely honor — a half-honored
+ * BYMONTHDAY would put events on wrong dates, which is worse than not expanding.
+ *
+ * Fully supported (expanded to real occurrences):
+ *  - FREQ = DAILY | WEEKLY | MONTHLY | YEARLY
+ *  - INTERVAL (default 1)
+ *  - COUNT  (occurrence cap)
+ *  - UNTIL  (inclusive end bound; DATE or date-time, 'Z' or floating)
+ *  - BYDAY  — ONLY for FREQ=WEEKLY with INTERVAL=1 and weekday-only tokens
+ *             (MO,TU,WE,TH,FR,SA,SU with no leading ordinal). Under those
+ *             conditions WKST does not change the matched set, so it is ignored
+ *             safely. Any BYDAY outside that condition is treated as unsupported.
+ *
+ * Everything else present in the RRULE (BYMONTHDAY, BYMONTH, BYSETPOS, BYHOUR,
+ * BYWEEKNO, BYYEARDAY, ordinal BYDAY, BYDAY on non-weekly, INTERVAL>1 with BYDAY,
+ * or an unknown FREQ) marks the rule `unsupported` and names the offending part.
+ *
+ * PURE: no fs, no network, no process globals.
+ */
+import type { CalendarEvent, DateWindow, EventOccurrence, RecurrenceInfo } from './types.js';
+/**
+ * Classify a raw RRULE into an honest RecurrenceInfo. Called by the parser at read
+ * time so the event carries its expansion verdict before any window is known.
+ */
+export declare function describeRecurrence(rule: string): RecurrenceInfo;
+/**
+ * Expand a (possibly recurring) event into concrete occurrences inside [window.from,
+ * window.to] inclusive. A non-recurring event yields at most its single seed. An
+ * event whose recurrence is `unsupported` yields ONLY its seed (if in-window),
+ * flagged `isSeed`, never a fabricated series — the caller reads
+ * `event.recurrence.expansion` to label it "recurrence not fully expanded".
+ */
+export declare function expandEvent(event: CalendarEvent, window: DateWindow): EventOccurrence[];
+//# sourceMappingURL=rrule.d.ts.map

package/dist/platform/calendar/rrule.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"rrule.d.ts","sourceRoot":"","sources":["../../../src/platform/calendar/rrule.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,OAAO,KAAK,EACV,aAAa,EACb,UAAU,EACV,eAAe,EACf,cAAc,EACf,MAAM,YAAY,CAAC;AA0BpB;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,cAAc,CAoB/D;AAiED;;;;;;GAMG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,aAAa,EAAE,MAAM,EAAE,UAAU,GAAG,eAAe,EAAE,CAqEvF"}