document360-engine 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Saravana Kumar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,47 @@
+# document360-engine
+
+Headless documentation-agent engine for [`document360-writer`](https://www.npmjs.com/package/document360-writer) and future GUI wrappers (e.g. `document360-desktop`).
+
+This package contains **no UI**. It exposes the agent session lifecycle, Document360 OAuth/profiles/config, and an in-process Document360 tool server, and emits a typed **event stream** that wrappers render however they like (terminal, GUI). It's the documentation analog of the Claude Agent SDK: one engine, many front-ends.
+
+> You almost certainly want `document360-writer` (the CLI), not this package directly. This is the shared core.
+
+## Concept
+
+```
+document360-engine            ← this package: headless, emits EngineEvents
+   ├─ document360-writer      ← terminal wrapper (CLI + Ink TUI)
+   └─ document360-desktop     ← (future) GUI wrapper
+```
+
+The engine never writes to a screen. Each wrapper does two things: **render events** and **collect input → engine calls**.
+
+## Minimal usage
+
+```ts
+import { createSession } from 'document360-engine';
+
+const session = createSession({ cwd: process.cwd(), authMode: 'auto' });
+for await (const event of session.send('analyze this repo and propose a docs structure')) {
+  switch (event.type) {
+    case 'text':   process.stdout.write(event.delta); break;       // streaming answer
+    case 'tool':   console.error(`tool: ${event.name}`); break;    // a tool was invoked
+    case 'result': console.error(`done: ${event.outputTokens} tokens`); break;
+    case 'error':  console.error(`error: ${event.message}`); break;
+  }
+}
+session.close();
+```
+
+All `EngineEvent` variants are plain JSON, so a wrapper can stream them over IPC to a GUI.
+
+## Also exported
+
+- **Document360 auth**: `loginPkce`, `whoami`, token store, `resolveActiveProfile`, profile helpers.
+- **Claude auth**: `resolveAuth` (`api` / `subscription` / `auto`).
+- **Config**: `readProjectConfig` / `writeProjectConfig`, `resolveProfile`, types.
+- **Sessions**: `createSession`, `listSessions`, `getSession`, `renameSession`, `generateTitle`.
+
+## License
+
+MIT

package/dist/config.d.ts

@@ -0,0 +1,73 @@
+/** How to reach a Document360 deployment. `environment` names a baked preset
+    (src/d360/environments.ts); any field present here overrides the preset. */
+export type ProfileConnection = {
+    environment?: string;
+    apiUrl?: string;
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    clientId?: string;
+    scopes?: string[];
+    redirectUri?: string;
+    acrValues?: string;
+    prompt?: string;
+};
+/** The Document360 project a profile acts on (chosen at login via project_select). */
+export type ProfileProject = {
+    projectId?: string;
+    workspaceId?: string;
+    languageCode?: string;
+};
+/** A named, switchable connection profile. `connection` is one aspect; more may be added. */
+export type Profile = {
+    connection: ProfileConnection;
+    project?: ProfileProject;
+    /** Guards writes (publish/update/upload) behind explicit confirmation. */
+    production?: boolean;
+};
+export type ProjectConfig = {
+    /** Writer's own label — scopes sessions/screenshots. Not the Document360 project. */
+    projectId: string;
+    captureDir?: string;
+    outputDir?: string;
+    authoritativeSourceFiles?: string[];
+    terminologyGlossary?: Record<string, string>;
+    defaultModel?: string;
+    /** Connection profiles. See plans/connection-profiles.md. */
+    profiles?: Record<string, Profile>;
+    defaultProfile?: string;
+};
+export declare class ProfileConfigError extends Error {
+}
+/** Resolve a profile by name (or the default). Throws a migration error if the config
+    predates profiles (no back-compat by design — single pattern). */
+export declare function resolveProfile(cfg: ProjectConfig | null, name?: string): {
+    name: string;
+    profile: Profile;
+};
+export type UserConfig = {
+    defaultModel?: string;
+    autoUpdate?: boolean;
+};
+export type McpServerEntry = {
+    type: 'stdio';
+    command: string;
+    args?: string[];
+    env?: Record<string, string>;
+} | {
+    type: 'http';
+    url: string;
+    headers?: Record<string, string>;
+} | {
+    type: 'sse';
+    url: string;
+    headers?: Record<string, string>;
+};
+export type UserMcpConfig = {
+    servers: Record<string, McpServerEntry>;
+};
+export declare function readProjectConfig(cwd?: string): ProjectConfig | null;
+export declare function writeProjectConfig(cfg: ProjectConfig, cwd?: string): void;
+export declare function readUserConfig(): UserConfig;
+export declare function writeUserConfig(cfg: UserConfig): void;
+export declare function readMcpConfig(): UserMcpConfig;
+export declare function writeMcpConfig(cfg: UserMcpConfig): void;

package/dist/config.js

@@ -0,0 +1,62 @@
+import { readFileSync, writeFileSync, existsSync } from 'node:fs';
+import { projectConfigPath, userConfigPath, userMcpConfigPath, userDir, ensureDir, } from './lib/paths.js';
+export class ProfileConfigError extends Error {
+}
+/** Resolve a profile by name (or the default). Throws a migration error if the config
+    predates profiles (no back-compat by design — single pattern). */
+export function resolveProfile(cfg, name) {
+    if (!cfg?.profiles || Object.keys(cfg.profiles).length === 0) {
+        throw new ProfileConfigError('No connection profiles in .d360-writer.json. This version requires a `profiles` map + ' +
+            '`defaultProfile` (the old d360.environment/projectId shape is no longer supported). ' +
+            'Run `d360-writer init` to scaffold the new shape.');
+    }
+    const chosen = name ?? cfg.defaultProfile;
+    if (!chosen) {
+        throw new ProfileConfigError(`No profile specified and no defaultProfile set. Available: ${Object.keys(cfg.profiles).join(', ')}`);
+    }
+    const profile = cfg.profiles[chosen];
+    if (!profile) {
+        throw new ProfileConfigError(`Unknown profile "${chosen}". Available: ${Object.keys(cfg.profiles).join(', ')}`);
+    }
+    return { name: chosen, profile };
+}
+export function readProjectConfig(cwd = process.cwd()) {
+    const path = projectConfigPath(cwd);
+    if (!existsSync(path))
+        return null;
+    return JSON.parse(readFileSync(path, 'utf8'));
+}
+export function writeProjectConfig(cfg, cwd = process.cwd()) {
+    writeFileSync(projectConfigPath(cwd), JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+}
+export function readUserConfig() {
+    const path = userConfigPath();
+    if (!existsSync(path))
+        return {};
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return {};
+    }
+}
+export function writeUserConfig(cfg) {
+    ensureDir(userDir());
+    writeFileSync(userConfigPath(), JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+}
+export function readMcpConfig() {
+    const path = userMcpConfigPath();
+    if (!existsSync(path))
+        return { servers: {} };
+    try {
+        return JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        return { servers: {} };
+    }
+}
+export function writeMcpConfig(cfg) {
+    ensureDir(userDir());
+    writeFileSync(userMcpConfigPath(), JSON.stringify(cfg, null, 2) + '\n', 'utf8');
+}
+//# sourceMappingURL=config.js.map

package/dist/config.js.map

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

package/dist/d360/client.d.ts

@@ -0,0 +1,30 @@
+import type { D360Environment } from './environments.js';
+/** Auth/connection context for a request: which profile's tokens + which connection. */
+export type D360Context = {
+    profile: string;
+    connection: D360Environment;
+};
+export declare class D360AuthError extends Error {
+}
+export declare class D360ApiError extends Error {
+    readonly status: number;
+    readonly requestId?: string | undefined;
+    constructor(message: string, status: number, requestId?: string | undefined);
+}
+/** Valid access token for the profile, refreshing if possible. Throws D360AuthError otherwise. */
+export declare function getAccessToken(ctx: D360Context): Promise<string>;
+/** The project the writer acts on: explicit (profile/arg) wins, else the token's doc360_project_id claim. */
+export declare function resolveProjectId(ctx: D360Context, configProjectId?: string): string;
+export type D360RequestOptions = {
+    query?: Record<string, string | number | boolean | undefined>;
+    body?: unknown;
+};
+/** Single request, returns the unwrapped `data`. */
+export declare function d360Get<T>(ctx: D360Context, path: string, opts?: D360RequestOptions): Promise<T>;
+export declare function d360Post<T>(ctx: D360Context, path: string, opts?: D360RequestOptions): Promise<T>;
+export declare function d360Patch<T>(ctx: D360Context, path: string, opts?: D360RequestOptions): Promise<T>;
+/** Multipart upload (Drive files). Does NOT set content-type — fetch derives the
+    multipart boundary from the FormData. Returns the unwrapped `data`. */
+export declare function d360Upload<T>(ctx: D360Context, path: string, form: FormData): Promise<T>;
+/** Cursor-paginated GET — follows pagination.next_cursor, concatenating data arrays. */
+export declare function d360GetAll<T>(ctx: D360Context, path: string, opts?: D360RequestOptions): Promise<T[]>;

package/dist/d360/client.js

@@ -0,0 +1,132 @@
+import { refreshTokens, toStoredTokens } from './oauth.js';
+import { decodeJwtClaims, isExpired, loadTokens, saveTokens } from './tokenStore.js';
+export class D360AuthError extends Error {
+}
+export class D360ApiError extends Error {
+    status;
+    requestId;
+    constructor(message, status, requestId) {
+        super(message);
+        this.status = status;
+        this.requestId = requestId;
+    }
+}
+/** Valid access token for the profile, refreshing if possible. Throws D360AuthError otherwise. */
+export async function getAccessToken(ctx) {
+    const tokens = loadTokens(ctx.profile);
+    if (!tokens) {
+        throw new D360AuthError(`Not logged in to Document360 (profile "${ctx.profile}"). Run: d360-writer login --profile ${ctx.profile}`);
+    }
+    if (!isExpired(tokens))
+        return tokens.accessToken;
+    if (!tokens.refreshToken) {
+        throw new D360AuthError(`Document360 session expired (profile "${ctx.profile}"). Run: d360-writer login --profile ${ctx.profile}`);
+    }
+    try {
+        const refreshed = toStoredTokens(ctx.profile, await refreshTokens(ctx.connection, tokens.refreshToken));
+        saveTokens(refreshed);
+        return refreshed.accessToken;
+    }
+    catch (err) {
+        throw new D360AuthError(`Document360 session expired and refresh failed (${err.message.slice(0, 120)}). Run: d360-writer login --profile ${ctx.profile}`);
+    }
+}
+/** The project the writer acts on: explicit (profile/arg) wins, else the token's doc360_project_id claim. */
+export function resolveProjectId(ctx, configProjectId) {
+    if (configProjectId)
+        return configProjectId;
+    const tokens = loadTokens(ctx.profile);
+    const claims = tokens ? (decodeJwtClaims(tokens.accessToken) ?? {}) : {};
+    const fromClaim = claims['doc360_project_id'];
+    if (typeof fromClaim === 'string' && fromClaim)
+        return fromClaim;
+    throw new D360AuthError('No Document360 project resolved. Log in (the project is chosen during login) or set the profile\'s project.projectId in .d360-writer.json.');
+}
+async function rawFetch(ctx, method, path, opts = {}) {
+    const token = await getAccessToken(ctx);
+    const url = new URL(path.startsWith('http') ? path : `${ctx.connection.apiUrl}${path}`);
+    for (const [k, v] of Object.entries(opts.query ?? {})) {
+        if (v !== undefined)
+            url.searchParams.set(k, String(v));
+    }
+    const res = await fetch(url, {
+        method,
+        headers: {
+            authorization: `Bearer ${token}`,
+            accept: 'application/json',
+            ...(opts.body !== undefined ? { 'content-type': 'application/json' } : {}),
+        },
+        body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+    });
+    const text = await res.text();
+    let envelope = {};
+    if (text) {
+        try {
+            envelope = JSON.parse(text);
+        }
+        catch {
+            /* non-JSON body — handled below */
+        }
+    }
+    if (!res.ok || envelope.success === false) {
+        const detail = envelope.errors?.map(e => e.message ?? e.code).filter(Boolean).join('; ') || text.slice(0, 300) || res.statusText;
+        if (res.status === 401) {
+            throw new D360AuthError(`Document360 rejected the token (401). Run: d360-writer login --profile ${ctx.profile}`);
+        }
+        throw new D360ApiError(`Document360 API ${res.status}: ${detail}`, res.status, envelope.request_id);
+    }
+    return envelope;
+}
+/** Single request, returns the unwrapped `data`. */
+export async function d360Get(ctx, path, opts) {
+    return (await rawFetch(ctx, 'GET', path, opts)).data;
+}
+export async function d360Post(ctx, path, opts) {
+    return (await rawFetch(ctx, 'POST', path, opts)).data;
+}
+export async function d360Patch(ctx, path, opts) {
+    return (await rawFetch(ctx, 'PATCH', path, opts)).data;
+}
+/** Multipart upload (Drive files). Does NOT set content-type — fetch derives the
+    multipart boundary from the FormData. Returns the unwrapped `data`. */
+export async function d360Upload(ctx, path, form) {
+    const token = await getAccessToken(ctx);
+    const res = await fetch(`${ctx.connection.apiUrl}${path}`, {
+        method: 'POST',
+        headers: { authorization: `Bearer ${token}`, accept: 'application/json' },
+        body: form,
+    });
+    const text = await res.text();
+    let envelope = {};
+    if (text) {
+        try {
+            envelope = JSON.parse(text);
+        }
+        catch {
+            /* non-JSON */
+        }
+    }
+    if (!res.ok || envelope.success === false) {
+        const detail = envelope.errors?.map(e => e.message ?? e.code).filter(Boolean).join('; ') || text.slice(0, 300) || res.statusText;
+        if (res.status === 401)
+            throw new D360AuthError(`Document360 rejected the token (401). Run: d360-writer login --profile ${ctx.profile}`);
+        throw new D360ApiError(`Document360 upload ${res.status}: ${detail}`, res.status, envelope.request_id);
+    }
+    return envelope.data;
+}
+/** Cursor-paginated GET — follows pagination.next_cursor, concatenating data arrays. */
+export async function d360GetAll(ctx, path, opts = {}) {
+    const out = [];
+    let cursor;
+    // Safety cap: 50 pages — a runaway pagination loop shouldn't hang the agent.
+    for (let page = 0; page < 50; page++) {
+        const envelope = await rawFetch(ctx, 'GET', path, { ...opts, query: { ...opts.query, cursor } });
+        if (Array.isArray(envelope.data))
+            out.push(...envelope.data);
+        if (!envelope.pagination?.has_more || !envelope.pagination.next_cursor)
+            break;
+        cursor = envelope.pagination.next_cursor;
+    }
+    return out;
+}
+//# sourceMappingURL=client.js.map

package/dist/d360/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../src/d360/client.ts"],"names":[],"mappings":"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"}

package/dist/d360/environments.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Document360 environment presets — baked defaults, overridable at runtime via
+ * D360_* env vars (decided in plans/first-party-d360-integration.md: no CI-variable
+ * injection; client_id etc. are PKCE public-client values, not secrets).
+ */
+import type { ProfileConnection } from '../config.js';
+export type D360Environment = {
+    /** Preset this connection is based on (display/label only; auth is keyed by PROFILE name). */
+    name: string;
+    apiUrl: string;
+    authorizationUrl: string;
+    tokenUrl: string;
+    clientId: string;
+    scopes: string[];
+    acrValues: string;
+    redirectUri: string;
+    /** OAuth prompt param. 'login' forces a fresh auth screen, avoiding stale-session/cached
+        error pages in the default browser (no incognito needed). Empty string omits it. */
+    prompt: string;
+};
+export declare function knownEnvironments(): string[];
+export declare function resolveEnvironment(name?: string): D360Environment;
+/**
+ * Resolve a profile's connection into a concrete D360Environment. Layering, lowest→highest:
+ * baked preset (named by `connection.environment`, default berlin) → inline profile fields →
+ * D360_* env vars (testing escape hatch).
+ */
+export declare function resolveConnection(connection: ProfileConnection): D360Environment;

package/dist/d360/environments.js

@@ -0,0 +1,54 @@
+const PRESETS = {
+    berlin: {
+        apiUrl: 'https://apihub.berlin.document360.net',
+        authorizationUrl: 'https://identity.berlin.document360.net/connect/authorize',
+        tokenUrl: 'https://identity.berlin.document360.net/connect/token',
+        // Dedicated d360-writer client, confirmed working for Customer API V3 OAuth
+        // on berlin (D360 API team, 2026-06-08).
+        clientId: 'd360WriterAgentClient',
+        // offline_access → refresh token (added to the client by the D360 API team 2026-06-08,
+        // resolving the 1h-session limitation).
+        scopes: ['openid', 'profile', 'email', 'customerApi', 'offline_access'],
+        // Identity server shows the project chooser during login; token is project-scoped.
+        acrValues: 'project_select',
+        // RFC 8252 loopback — whitelisted for d360WriterAgentClient (D360 API team,
+        // 2026-06-08). Port 3223 is fixed because the redirect URI must match the
+        // registered value exactly. Override with D360_REDIRECT_URI only for testing.
+        redirectUri: 'http://127.0.0.1:3223/callback',
+        // Force a fresh login screen so a stale browser session/cached error page can't
+        // hijack the flow (was forcing users into incognito). Override with D360_PROMPT.
+        prompt: 'login',
+    },
+    // production: filled at Document360 OAuth GA (end of June 2026).
+};
+export function knownEnvironments() {
+    return Object.keys(PRESETS);
+}
+export function resolveEnvironment(name = 'berlin') {
+    return resolveConnection({ environment: name });
+}
+/**
+ * Resolve a profile's connection into a concrete D360Environment. Layering, lowest→highest:
+ * baked preset (named by `connection.environment`, default berlin) → inline profile fields →
+ * D360_* env vars (testing escape hatch).
+ */
+export function resolveConnection(connection) {
+    const presetName = connection.environment ?? 'berlin';
+    const preset = PRESETS[presetName];
+    if (!preset) {
+        throw new Error(`Unknown Document360 environment "${presetName}". Known: ${knownEnvironments().join(', ')}`);
+    }
+    const envScopes = process.env.D360_SCOPES?.split(/[\s,]+/).filter(Boolean);
+    return {
+        name: presetName,
+        apiUrl: process.env.D360_API_URL ?? connection.apiUrl ?? preset.apiUrl,
+        authorizationUrl: process.env.D360_AUTHORIZATION_URL ?? connection.authorizationUrl ?? preset.authorizationUrl,
+        tokenUrl: process.env.D360_TOKEN_URL ?? connection.tokenUrl ?? preset.tokenUrl,
+        clientId: process.env.D360_CLIENT_ID ?? connection.clientId ?? preset.clientId,
+        scopes: envScopes ?? connection.scopes ?? preset.scopes,
+        acrValues: process.env.D360_ACR_VALUES ?? connection.acrValues ?? preset.acrValues,
+        redirectUri: process.env.D360_REDIRECT_URI ?? connection.redirectUri ?? preset.redirectUri,
+        prompt: process.env.D360_PROMPT ?? connection.prompt ?? preset.prompt,
+    };
+}
+//# sourceMappingURL=environments.js.map

package/dist/d360/environments.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"environments.js","sourceRoot":"","sources":["../../src/d360/environments.ts"],"names":[],"mappings":"AAsBA,MAAM,OAAO,GAAkD;IAC7D,MAAM,EAAE;QACN,MAAM,EAAE,uCAAuC;QAC/C,gBAAgB,EAAE,2DAA2D;QAC7E,QAAQ,EAAE,uDAAuD;QACjE,4EAA4E;QAC5E,yCAAyC;QACzC,QAAQ,EAAE,uBAAuB;QACjC,uFAAuF;QACvF,wCAAwC;QACxC,MAAM,EAAE,CAAC,QAAQ,EAAE,SAAS,EAAE,OAAO,EAAE,aAAa,EAAE,gBAAgB,CAAC;QACvE,mFAAmF;QACnF,SAAS,EAAE,gBAAgB;QAC3B,4EAA4E;QAC5E,0EAA0E;QAC1E,8EAA8E;QAC9E,WAAW,EAAE,gCAAgC;QAC7C,gFAAgF;QAChF,iFAAiF;QACjF,MAAM,EAAE,OAAO;KAChB;IACD,iEAAiE;CAClE,CAAC;AAEF,MAAM,UAAU,iBAAiB;IAC/B,OAAO,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;AAC9B,CAAC;AAED,MAAM,UAAU,kBAAkB,CAAC,IAAI,GAAG,QAAQ;IAChD,OAAO,iBAAiB,CAAC,EAAE,WAAW,EAAE,IAAI,EAAE,CAAC,CAAC;AAClD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,UAA6B;IAC7D,MAAM,UAAU,GAAG,UAAU,CAAC,WAAW,IAAI,QAAQ,CAAC;IACtD,MAAM,MAAM,GAAG,OAAO,CAAC,UAAU,CAAC,CAAC;IACnC,IAAI,CAAC,MAAM,EAAE,CAAC;QACZ,MAAM,IAAI,KAAK,CAAC,oCAAoC,UAAU,aAAa,iBAAiB,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,EAAE,CAAC,CAAC;IAC/G,CAAC;IACD,MAAM,SAAS,GAAG,OAAO,CAAC,GAAG,CAAC,WAAW,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;IAC3E,OAAO;QACL,IAAI,EAAE,UAAU;QAChB,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,YAAY,IAAI,UAAU,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM;QACtE,gBAAgB,EAAE,OAAO,CAAC,GAAG,CAAC,sBAAsB,IAAI,UAAU,CAAC,gBAAgB,IAAI,MAAM,CAAC,gBAAgB;QAC9G,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,UAAU,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ;QAC9E,QAAQ,EAAE,OAAO,CAAC,GAAG,CAAC,cAAc,IAAI,UAAU,CAAC,QAAQ,IAAI,MAAM,CAAC,QAAQ;QAC9E,MAAM,EAAE,SAAS,IAAI,UAAU,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM;QACvD,SAAS,EAAE,OAAO,CAAC,GAAG,CAAC,eAAe,IAAI,UAAU,CAAC,SAAS,IAAI,MAAM,CAAC,SAAS;QAClF,WAAW,EAAE,OAAO,CAAC,GAAG,CAAC,iBAAiB,IAAI,UAAU,CAAC,WAAW,IAAI,MAAM,CAAC,WAAW;QAC1F,MAAM,EAAE,OAAO,CAAC,GAAG,CAAC,WAAW,IAAI,UAAU,CAAC,MAAM,IAAI,MAAM,CAAC,MAAM;KACtE,CAAC;AACJ,CAAC"}

package/dist/d360/oauth.d.ts

@@ -0,0 +1,27 @@
+import type { D360Environment } from './environments.js';
+import type { StoredTokens } from './tokenStore.js';
+export type TokenResponse = {
+    access_token: string;
+    token_type: string;
+    expires_in: number;
+    refresh_token?: string;
+    id_token?: string;
+    scope?: string;
+};
+export declare function buildAuthorizationUrl(env: D360Environment): {
+    url: string;
+    verifier: string;
+    state: string;
+};
+export declare function exchangeCode(env: D360Environment, code: string, verifier: string): Promise<TokenResponse>;
+export declare function refreshTokens(env: D360Environment, refreshToken: string): Promise<TokenResponse>;
+export declare function toStoredTokens(profile: string, t: TokenResponse): StoredTokens;
+/**
+ * Interactive login. Default: loopback listener + browser. Manual mode: no
+ * listener — the user pastes the full redirect URL (works even when the
+ * registered redirect URI is not a loopback we can bind).
+ */
+export declare function loginPkce(env: D360Environment, opts: {
+    manual?: boolean;
+    promptForRedirect: (msg: string) => Promise<string>;
+}, log: (line: string) => void): Promise<TokenResponse>;