forkit-connect 0.1.0

package/dist/v1/api.d.ts

@@ -0,0 +1,276 @@
+import type { ConnectEffectiveBindingState } from './types';
+export interface ConnectApiConfig {
+    baseUrl: string;
+    sessionRef: string | null;
+}
+export interface ApiCallResult {
+    ok: boolean;
+    status: number;
+    body: unknown;
+    contract: ApiContractInfo | null;
+}
+export interface ApiContractInfo {
+    version: string | null;
+    compatibility: string | null;
+    mode: string | null;
+    min_client_version: string | null;
+    route_capabilities: string[];
+    server_capabilities: string[];
+    warnings: string[];
+}
+export interface DeviceConnectStartResponse {
+    device_code: string;
+    user_code: string;
+    verification_url: string;
+    expires_at: string;
+    poll_interval_seconds: number;
+    binding_id?: string;
+    state?: string;
+}
+export interface DeviceConnectPollPendingResponse {
+    status: 'pending';
+    poll_interval_seconds?: number;
+    expires_at?: string;
+}
+export interface DeviceConnectPollApprovedResponse {
+    status: 'approved';
+    connect_access_token: string;
+    token_type: 'Bearer';
+    expires_in_seconds: number;
+    binding?: Record<string, unknown> | null;
+}
+export interface DeviceConnectStartRequest {
+    connect_device_id?: string | null;
+    connect_public_key?: string | null;
+    device_label?: string | null;
+    client_version?: string | null;
+    platform?: string | null;
+    arch?: string | null;
+}
+export type EffectiveBindingResponse = Omit<ConnectEffectiveBindingState, 'fetched_at'>;
+export interface ProfileAccessWorkspace {
+    id?: string | null;
+    gaid?: string | null;
+    passportGaid?: string | null;
+    workspaceKind?: 'governed_container' | 'passport_shell' | string;
+    name?: string | null;
+    passportType?: 'model' | 'agent' | 'dataset' | string | null;
+    role?: 'owner' | 'maintainer' | 'contributor' | string;
+    ownerId?: string | null;
+    ownerName?: string | null;
+    description?: string | null;
+    visibility?: 'private' | 'public' | string;
+    verificationStatus?: 'unverified' | 'verified' | 'revoked' | string;
+    lifecycleStatus?: 'active' | 'deactivated' | string;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+export interface ProfileAccessResponse {
+    summary?: {
+        platformRole?: string;
+        tier?: string;
+    };
+    workspaces?: ProfileAccessWorkspace[];
+}
+export interface ProductSummaryResponse {
+    tier?: string | null;
+    baseTier?: string | null;
+    package?: {
+        slug?: string | null;
+        name?: string | null;
+        baseTier?: string | null;
+    } | null;
+    planCapabilities?: {
+        planKey?: string | null;
+        registration?: {
+            privatePassports?: number | null;
+            draftPassports?: number | null;
+            apiKeysPerPassport?: number | null;
+            activationTokensPerPassport?: number | null;
+        } | null;
+        governance?: {
+            maxGovernedProjects?: number | null;
+            maxGovernedWorkspaces?: number | null;
+            maxGovernedPassports?: number | null;
+        } | null;
+        runtimeSignals?: {
+            runtimeSignalsPerMonth?: number | null;
+        } | null;
+    } | null;
+    entitlements?: {
+        privatePassports?: number | null;
+        draftPassports?: number | null;
+        apiKeysPerPassport?: number | null;
+        activationTokensPerPassport?: number | null;
+        maxProjects?: number | null;
+        maxWorkspaces?: number | null;
+        maxGovernedPassports?: number | null;
+    } | null;
+    usage?: {
+        passports?: number | null;
+        privatePassports?: number | null;
+        drafts?: number | null;
+        projects?: number | null;
+        runtimeSignals?: number | null;
+    } | null;
+}
+export interface WorkspaceProject {
+    id?: string | null;
+    workspaceId?: string | null;
+    name?: string | null;
+    description?: string | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+    passportCount?: number | null;
+    status?: string | null;
+}
+export interface WorkspaceProjectsResponse {
+    workspace?: ProfileAccessWorkspace | Record<string, unknown> | null;
+    projects?: WorkspaceProject[];
+}
+export interface WorkspaceCreateResponse {
+    workspace?: ProfileAccessWorkspace | Record<string, unknown> | null;
+}
+export interface WorkspaceProjectCreateResponse {
+    workspace?: ProfileAccessWorkspace | Record<string, unknown> | null;
+    project?: WorkspaceProject | null;
+}
+export interface PassportDraft {
+    id?: string | null;
+    ownerId?: string | null;
+    passportType?: string | null;
+    name?: string | null;
+    payload?: Record<string, unknown> | null;
+    createdAt?: string | null;
+    updatedAt?: string | null;
+}
+export interface PassportDraftListResponse {
+    drafts?: PassportDraft[];
+    tier?: string | null;
+    entitlements?: Record<string, unknown> | null;
+}
+export interface PassportDraftResponse {
+    draft?: PassportDraft | null;
+}
+export interface PassportDraftPublishResponse {
+    draftId?: string | null;
+    draftState?: string | null;
+    draft?: PassportDraft | null;
+    passport?: {
+        id?: number | null;
+        gaid?: string | null;
+        name?: string | null;
+        passportType?: string | null;
+        workspaceId?: string | null;
+        projectId?: string | null;
+        connectionStatus?: string | null;
+    } | null;
+}
+export interface PassportResponse {
+    passport?: {
+        id?: number | string | null;
+        gaid?: string | null;
+        name?: string | null;
+        passportType?: string | null;
+        workspaceId?: string | null;
+        projectId?: string | null;
+        connectionStatus?: string | null;
+        metadata?: Record<string, unknown> | null;
+    } | null;
+}
+export interface DeploymentCheckinRequest {
+    binding_id?: string | null;
+    sessionId?: string;
+    sessionLabel?: string;
+    environment?: string;
+    region?: string;
+    hostLabel?: string;
+    runtimeLabel?: string;
+    runtimeMode?: 'active' | 'paused' | 'draining' | string;
+    resourceAccuracy?: 'unknown' | 'measured' | 'estimated' | string;
+    resourceNote?: string;
+    metadata?: Record<string, unknown>;
+}
+export interface DeploymentCheckinResponse {
+    gaid?: string | null;
+    session?: {
+        sessionId?: string | null;
+        sessionLabel?: string | null;
+        environment?: string | null;
+        region?: string | null;
+        hostLabel?: string | null;
+        runtimeLabel?: string | null;
+        runtimeMode?: string | null;
+        revokedAt?: string | null;
+        resourceAccuracy?: string | null;
+        lastCheckinAt?: string | null;
+        metadata?: Record<string, unknown> | null;
+    } | null;
+}
+export interface DeploymentSessionResponse {
+    sessionId?: string | null;
+    sessionLabel?: string | null;
+    environment?: string | null;
+    region?: string | null;
+    hostLabel?: string | null;
+    runtimeLabel?: string | null;
+    runtimeMode?: string | null;
+    resourceAccuracy?: string | null;
+    lastCheckinAt?: string | null;
+    firstSeenAt?: string | null;
+    revokedAt?: string | null;
+    apiKeyId?: string | null;
+    metadata?: Record<string, unknown> | null;
+}
+export interface DeploymentListResponse {
+    gaid?: string | null;
+    summary?: {
+        totalSessions?: number | null;
+        activeSessions?: number | null;
+        standbySessions?: number | null;
+        sleepingSessions?: number | null;
+        offlineSessions?: number | null;
+    } | null;
+    sessions?: DeploymentSessionResponse[];
+}
+export declare class ConnectApiClient {
+    private readonly config;
+    constructor(config: ConnectApiConfig);
+    private getHeaders;
+    private parseContract;
+    getPassportsMine(limit?: number): Promise<ApiCallResult>;
+    getProductSummary(): Promise<ApiCallResult>;
+    createPassportDraft(payload: Record<string, unknown>): Promise<ApiCallResult>;
+    pushRuntimeSignalEvent(payload: Record<string, unknown>): Promise<ApiCallResult>;
+    getDeployments(gaid: string): Promise<ApiCallResult>;
+    sendDeploymentCheckin(gaid: string, payload: DeploymentCheckinRequest): Promise<ApiCallResult>;
+    getProfileAccess(): Promise<ApiCallResult>;
+    getWorkspaceProjects(workspaceId: string): Promise<ApiCallResult>;
+    createWorkspace(payload: {
+        name: string;
+        description?: string | null;
+    }): Promise<ApiCallResult>;
+    createWorkspaceProject(workspaceId: string, payload: {
+        name: string;
+        description?: string | null;
+    }): Promise<ApiCallResult>;
+    getPassportDrafts(): Promise<ApiCallResult>;
+    getPassportDraft(draftId: string): Promise<ApiCallResult>;
+    getPassport(gaid: string): Promise<ApiCallResult>;
+    publishPassportDraft(draftId: string): Promise<ApiCallResult>;
+    deletePassportDraft(draftId: string): Promise<ApiCallResult>;
+    startDeviceConnect(payload?: DeviceConnectStartRequest): Promise<ApiCallResult>;
+    pollDeviceConnect(deviceCode: string): Promise<ApiCallResult>;
+    getEffectiveBinding(connectDeviceId?: string | null): Promise<ApiCallResult>;
+    assignBindingScope(bindingId: string, workspaceId: string, projectId: string): Promise<ApiCallResult>;
+    updateBindingConsent(bindingId: string, consentProfile: unknown): Promise<ApiCallResult>;
+    refreshBindingPresence(bindingId: string, payload?: Record<string, unknown>): Promise<ApiCallResult>;
+    /**
+     * POST /api/v1/passports/:gaid/api-keys
+     * Requires session token (Bearer auth). Creates a runtime-signal API key for the
+     * owned passport. Returns the rawKey exactly once — caller must persist it.
+     */
+    createPassportApiKey(gaid: string, label?: string): Promise<ApiCallResult>;
+    private parseBody;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/v1/api.js

@@ -0,0 +1,390 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ConnectApiClient = void 0;
+const CONNECT_API_CONTRACT_VERSION = 'connect.v1';
+const CONNECT_API_CLIENT_CAPABILITIES = [
+    'additive-json',
+    'binding-capability-profile-v1',
+    'binding-consent-profile-v1',
+    'binding-presence-v1',
+];
+function readConnectClientVersion() {
+    const configured = String(process.env.FORKIT_CONNECT_VERSION || '').trim();
+    return configured || '0.1.0-local';
+}
+function parseCapabilityHeader(value) {
+    return [...new Set(String(value || '')
+            .split(',')
+            .map((entry) => entry.trim().toLowerCase())
+            .filter(Boolean))];
+}
+class ConnectApiClient {
+    config;
+    constructor(config) {
+        this.config = config;
+    }
+    getHeaders(extra) {
+        const headers = {
+            'Content-Type': 'application/json',
+            'X-Forkit-Client-Name': 'forkit-connect',
+            'X-Forkit-Client-Version': readConnectClientVersion(),
+            'X-Forkit-Contract-Version': CONNECT_API_CONTRACT_VERSION,
+            'X-Forkit-Client-Capabilities': CONNECT_API_CLIENT_CAPABILITIES.join(','),
+            ...extra,
+        };
+        if (this.config.sessionRef) {
+            headers.Authorization = `Bearer ${this.config.sessionRef}`;
+        }
+        return headers;
+    }
+    parseContract(res) {
+        const version = res.headers.get('x-forkit-contract-version');
+        const compatibility = res.headers.get('x-forkit-contract-compatibility');
+        const mode = res.headers.get('x-forkit-contract-mode');
+        const minClientVersion = res.headers.get('x-forkit-min-client-version');
+        const routeCapabilities = parseCapabilityHeader(res.headers.get('x-forkit-route-capabilities'));
+        const serverCapabilities = parseCapabilityHeader(res.headers.get('x-forkit-server-capabilities'));
+        const warningsHeader = res.headers.get('x-forkit-contract-warnings');
+        if (!version
+            && !compatibility
+            && !mode
+            && !minClientVersion
+            && routeCapabilities.length === 0
+            && serverCapabilities.length === 0
+            && !warningsHeader) {
+            return null;
+        }
+        return {
+            version: version || null,
+            compatibility: compatibility || null,
+            mode: mode || null,
+            min_client_version: minClientVersion || null,
+            route_capabilities: routeCapabilities,
+            server_capabilities: serverCapabilities,
+            warnings: String(warningsHeader || '')
+                .split('|')
+                .map((entry) => entry.trim())
+                .filter(Boolean),
+        };
+    }
+    async getPassportsMine(limit = 100) {
+        const safeLimit = Math.min(Math.max(Math.trunc(Number(limit) || 100), 1), 100);
+        const url = `${this.config.baseUrl}/api/v1/passports/mine?limit=${safeLimit}`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async getProductSummary() {
+        const url = `${this.config.baseUrl}/product/summary`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async createPassportDraft(payload) {
+        const url = `${this.config.baseUrl}/api/v1/passport-drafts`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(payload),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async pushRuntimeSignalEvent(payload) {
+        const url = `${this.config.baseUrl}/api/v1/runtime-signals/events`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(payload),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async getDeployments(gaid) {
+        const url = `${this.config.baseUrl}/api/v1/passports/${encodeURIComponent(gaid)}/deployments`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async sendDeploymentCheckin(gaid, payload) {
+        const url = `${this.config.baseUrl}/api/v1/passports/${encodeURIComponent(gaid)}/deployments/checkin`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(payload),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async getProfileAccess() {
+        const url = `${this.config.baseUrl}/api/profiles/access`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async getWorkspaceProjects(workspaceId) {
+        const url = `${this.config.baseUrl}/api/v1/workspaces/${encodeURIComponent(workspaceId)}/projects`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async createWorkspace(payload) {
+        const url = `${this.config.baseUrl}/api/v1/workspaces`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(payload),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async createWorkspaceProject(workspaceId, payload) {
+        const url = `${this.config.baseUrl}/api/v1/workspaces/${encodeURIComponent(workspaceId)}/projects`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(payload),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async getPassportDrafts() {
+        const url = `${this.config.baseUrl}/api/v1/passport-drafts`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async getPassportDraft(draftId) {
+        const url = `${this.config.baseUrl}/api/v1/passport-drafts/${encodeURIComponent(draftId)}`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async getPassport(gaid) {
+        const url = `${this.config.baseUrl}/api/v1/passports/${encodeURIComponent(gaid)}`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: this.getHeaders(),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async publishPassportDraft(draftId) {
+        const url = `${this.config.baseUrl}/api/v1/passport-drafts/${encodeURIComponent(draftId)}/publish`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({}),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async deletePassportDraft(draftId) {
+        const url = `${this.config.baseUrl}/api/v1/passport-drafts/${encodeURIComponent(draftId)}`;
+        const res = await fetch(url, {
+            method: 'DELETE',
+            headers: this.getHeaders(),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async startDeviceConnect(payload = {}) {
+        const url = `${this.config.baseUrl}/api/auth/connect/device/start`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(payload),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async pollDeviceConnect(deviceCode) {
+        const url = `${this.config.baseUrl}/api/auth/connect/device/poll`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({ device_code: deviceCode }),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async getEffectiveBinding(connectDeviceId) {
+        const url = `${this.config.baseUrl}/api/v1/connect/bindings/effective`;
+        const res = await fetch(url, {
+            method: 'GET',
+            headers: this.getHeaders(connectDeviceId
+                ? { 'X-Connect-Device-Id': connectDeviceId }
+                : undefined),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async assignBindingScope(bindingId, workspaceId, projectId) {
+        const url = `${this.config.baseUrl}/api/v1/connect/bindings/${encodeURIComponent(bindingId)}/scope`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({
+                workspace_id: workspaceId,
+                project_id: projectId,
+            }),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async updateBindingConsent(bindingId, consentProfile) {
+        const url = `${this.config.baseUrl}/api/v1/connect/bindings/${encodeURIComponent(bindingId)}/consent`;
+        const res = await fetch(url, {
+            method: 'PATCH',
+            headers: this.getHeaders(),
+            body: JSON.stringify({
+                consent_profile: consentProfile,
+            }),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async refreshBindingPresence(bindingId, payload = {}) {
+        const url = `${this.config.baseUrl}/api/v1/connect/bindings/${encodeURIComponent(bindingId)}/presence`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify(payload),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    /**
+     * POST /api/v1/passports/:gaid/api-keys
+     * Requires session token (Bearer auth). Creates a runtime-signal API key for the
+     * owned passport. Returns the rawKey exactly once — caller must persist it.
+     */
+    async createPassportApiKey(gaid, label) {
+        const url = `${this.config.baseUrl}/api/v1/passports/${encodeURIComponent(gaid)}/api-keys`;
+        const res = await fetch(url, {
+            method: 'POST',
+            headers: this.getHeaders(),
+            body: JSON.stringify({ label: label ?? 'Forkit Connect (auto)' }),
+        });
+        return {
+            ok: res.ok,
+            status: res.status,
+            body: await this.parseBody(res),
+            contract: this.parseContract(res),
+        };
+    }
+    async parseBody(res) {
+        const contentType = res.headers.get('content-type') ?? '';
+        if (contentType.includes('application/json')) {
+            return res.json();
+        }
+        return res.text();
+    }
+}
+exports.ConnectApiClient = ConnectApiClient;
+//# sourceMappingURL=api.js.map