@kosha-ai/integration-sdk 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Codemancers
+
+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,11 @@
+# integration-sdk
+
+This library was generated with [Nx](https://nx.dev).
+
+## Building
+
+Run `nx build integration-sdk` to build the library.
+
+## Running unit tests
+
+Run `nx test integration-sdk` to execute the unit tests via [Jest](https://jestjs.io).

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export * from './lib/types.js';
+export { defineIntegration, httpFor, IntegrationDefinitionError, } from './lib/define-integration.js';
+export { oauth2, OAuth2Error, s256Challenge, generateCodeVerifier, type OAuth2Options, } from './lib/oauth2.js';
+export { createIntegrationHttp, IntegrationHttpError } from './lib/http.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,gBAAgB,CAAC;AAC/B,OAAO,EACL,iBAAiB,EACjB,OAAO,EACP,0BAA0B,GAC3B,MAAM,6BAA6B,CAAC;AACrC,OAAO,EACL,MAAM,EACN,WAAW,EACX,aAAa,EACb,oBAAoB,EACpB,KAAK,aAAa,GACnB,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC"}

package/dist/index.js

@@ -0,0 +1,4 @@
+export * from './lib/types.js';
+export { defineIntegration, httpFor, IntegrationDefinitionError, } from './lib/define-integration.js';
+export { oauth2, OAuth2Error, s256Challenge, generateCodeVerifier, } from './lib/oauth2.js';
+export { createIntegrationHttp, IntegrationHttpError } from './lib/http.js';

package/dist/lib/define-integration.d.ts

@@ -0,0 +1,15 @@
+import type { IntegrationHttp, KoshaIntegration } from './types.js';
+export declare class IntegrationDefinitionError extends Error {
+    constructor(message: string);
+}
+/**
+ * Validates an integration definition and returns it unchanged.
+ *
+ * Validation runs at definition time — i.e. at server boot, before the first
+ * request — so a malformed integration fails startup loudly instead of
+ * half-registering and erroring later on someone's OAuth callback.
+ */
+export declare function defineIntegration(definition: KoshaIntegration): KoshaIntegration;
+/** The HTTP client the server passes to `identity.fetchAccount`. */
+export declare function httpFor(integration: KoshaIntegration): IntegrationHttp;
+//# sourceMappingURL=define-integration.d.ts.map

package/dist/lib/define-integration.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define-integration.d.ts","sourceRoot":"","sources":["../../src/lib/define-integration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAEpE,qBAAa,0BAA2B,SAAQ,KAAK;gBACvC,OAAO,EAAE,MAAM;CAI5B;AAID;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAC/B,UAAU,EAAE,gBAAgB,GAC3B,gBAAgB,CAqDlB;AAED,oEAAoE;AACpE,wBAAgB,OAAO,CAAC,WAAW,EAAE,gBAAgB,GAAG,eAAe,CAMtE"}

package/dist/lib/define-integration.js

@@ -0,0 +1,67 @@
+import { createIntegrationHttp } from './http.js';
+export class IntegrationDefinitionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'IntegrationDefinitionError';
+    }
+}
+const KEY_PATTERN = /^[a-z][a-z0-9-]*$/;
+/**
+ * Validates an integration definition and returns it unchanged.
+ *
+ * Validation runs at definition time — i.e. at server boot, before the first
+ * request — so a malformed integration fails startup loudly instead of
+ * half-registering and erroring later on someone's OAuth callback.
+ */
+export function defineIntegration(definition) {
+    const problems = [];
+    if (!definition.key || !KEY_PATTERN.test(definition.key)) {
+        problems.push(`key must be lowercase alphanumeric with dashes, got ${JSON.stringify(definition.key)}`);
+    }
+    if (!definition.name)
+        problems.push('name is required');
+    if (!definition.auth) {
+        problems.push('auth is required');
+    }
+    else {
+        if (typeof definition.auth.buildAuthorizationUrl !== 'function') {
+            problems.push('auth.buildAuthorizationUrl must be a function');
+        }
+        if (typeof definition.auth.exchangeCode !== 'function') {
+            problems.push('auth.exchangeCode must be a function');
+        }
+        if (!Array.isArray(definition.auth.scopesAvailable)) {
+            problems.push('auth.scopesAvailable must be an array');
+        }
+    }
+    if (!definition.api?.baseUrl) {
+        problems.push('api.baseUrl is required');
+    }
+    else if (!/^https?:\/\//.test(definition.api.baseUrl)) {
+        problems.push(`api.baseUrl must be absolute, got ${definition.api.baseUrl}`);
+    }
+    if (definition.api && typeof definition.api.authHeaders !== 'function') {
+        problems.push('api.authHeaders must be a function');
+    }
+    if (typeof definition.identity?.fetchAccount !== 'function') {
+        problems.push('identity.fetchAccount must be a function');
+    }
+    for (const field of definition.configFields ?? []) {
+        if (!field.key)
+            problems.push('configFields[].key is required');
+        if (field.type === 'select' && !field.options?.length) {
+            problems.push(`configFields.${field.key} is a select with no options`);
+        }
+    }
+    if (problems.length > 0) {
+        throw new IntegrationDefinitionError(`Invalid integration "${definition.key ?? '<unnamed>'}":\n  - ${problems.join('\n  - ')}`);
+    }
+    return definition;
+}
+/** The HTTP client the server passes to `identity.fetchAccount`. */
+export function httpFor(integration) {
+    return createIntegrationHttp({
+        baseUrl: integration.api.baseUrl,
+        authHeaders: ({ accessToken }) => integration.api.authHeaders({ accessToken }),
+    });
+}

package/dist/lib/http.d.ts

@@ -0,0 +1,18 @@
+import type { IntegrationHttp } from './types.js';
+export declare class IntegrationHttpError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(message: string, status: number, body: unknown);
+}
+/**
+ * The HTTP client handed to integrations. Deliberately thin: integrations
+ * describe providers, they should not each ship a request layer.
+ */
+export declare function createIntegrationHttp(options: {
+    baseUrl: string;
+    defaultHeaders?: Record<string, string>;
+    authHeaders?: (credential: {
+        accessToken: string;
+    }) => Record<string, string>;
+}): IntegrationHttp;
+//# sourceMappingURL=http.d.ts.map

package/dist/lib/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/lib/http.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAA0B,MAAM,YAAY,CAAC;AAE1E,qBAAa,oBAAqB,SAAQ,KAAK;IAG3C,QAAQ,CAAC,MAAM,EAAE,MAAM;IACvB,QAAQ,CAAC,IAAI,EAAE,OAAO;gBAFtB,OAAO,EAAE,MAAM,EACN,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO;CAKzB;AAgBD;;;GAGG;AACH,wBAAgB,qBAAqB,CAAC,OAAO,EAAE;IAC7C,OAAO,EAAE,MAAM,CAAC;IAChB,cAAc,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACxC,WAAW,CAAC,EAAE,CAAC,UAAU,EAAE;QAAE,WAAW,EAAE,MAAM,CAAA;KAAE,KAAK,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC/E,GAAG,eAAe,CA2ClB"}

package/dist/lib/http.js

@@ -0,0 +1,61 @@
+export class IntegrationHttpError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.status = status;
+        this.body = body;
+        this.name = 'IntegrationHttpError';
+    }
+}
+function buildUrl(baseUrl, path, query) {
+    const url = new URL(path.startsWith('http') ? path : `${baseUrl.replace(/\/$/, '')}${path}`);
+    for (const [key, value] of Object.entries(query ?? {})) {
+        if (value !== undefined)
+            url.searchParams.set(key, String(value));
+    }
+    return url.toString();
+}
+/**
+ * The HTTP client handed to integrations. Deliberately thin: integrations
+ * describe providers, they should not each ship a request layer.
+ */
+export function createIntegrationHttp(options) {
+    const request = async (path, init = {}) => {
+        const headers = {
+            Accept: 'application/json',
+            ...options.defaultHeaders,
+            ...(init.accessToken && options.authHeaders
+                ? options.authHeaders({ accessToken: init.accessToken })
+                : {}),
+            ...init.headers,
+        };
+        if (init.body !== undefined && !headers['Content-Type']) {
+            headers['Content-Type'] = 'application/json';
+        }
+        const response = await fetch(buildUrl(options.baseUrl, path, init.query), {
+            method: init.method ?? (init.body === undefined ? 'GET' : 'POST'),
+            headers,
+            body: init.body === undefined ? undefined : JSON.stringify(init.body),
+        });
+        const text = await response.text();
+        const parsed = text ? safeJsonParse(text) : undefined;
+        if (!response.ok) {
+            throw new IntegrationHttpError(`Request to ${path} failed with ${response.status}`, response.status, parsed ?? text);
+        }
+        return parsed;
+    };
+    return {
+        request,
+        get: (path, init) => request(path, { ...init, method: 'GET' }),
+        post: (path, init) => request(path, { ...init, method: 'POST' }),
+    };
+}
+function safeJsonParse(text) {
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        return text;
+    }
+}

package/dist/lib/oauth2.d.ts

@@ -0,0 +1,36 @@
+import type { AuthorizationUrlArgs, ExchangeCodeArgs, IntegrationAuthStrategy, RefreshArgs, TokenSet } from './types.js';
+export interface OAuth2Options {
+    authorizationUrl: string;
+    tokenUrl: string;
+    revokeUrl?: string;
+    scopesAvailable: string[];
+    /** Separator the provider expects between scopes. GitHub uses a space. */
+    scopeSeparator?: string;
+    /** Extra static params on the authorize redirect (e.g. `{ prompt: 'consent' }`). */
+    authorizationParams?: Record<string, string>;
+    /** Providers disagree: GitHub wants JSON, most want form-encoded. */
+    tokenRequest?: 'json' | 'form';
+    pkce?: boolean;
+    /** Per-step overrides for providers that deviate from the spec. */
+    buildAuthorizationUrl?(args: AuthorizationUrlArgs): string;
+    exchangeCode?(args: ExchangeCodeArgs): Promise<TokenSet>;
+    refresh?(args: RefreshArgs): Promise<TokenSet>;
+    /** Map a non-standard token response onto {@link TokenSet}. */
+    parseTokenResponse?(body: Record<string, unknown>): TokenSet;
+}
+export declare class OAuth2Error extends Error {
+    constructor(message: string);
+}
+/**
+ * A complete OAuth2 authorization-code implementation. An integration supplies
+ * endpoints and scopes; this handles the redirect, the exchange, and refresh.
+ */
+export declare function oauth2(options: OAuth2Options): IntegrationAuthStrategy;
+/** RFC 7636 S256: base64url(sha256(verifier)). */
+export declare function s256Challenge(verifier: string): string;
+/**
+ * A PKCE code verifier: 43-128 unreserved characters. base64url of 32 random
+ * bytes lands at 43.
+ */
+export declare function generateCodeVerifier(): string;
+//# sourceMappingURL=oauth2.d.ts.map

package/dist/lib/oauth2.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"oauth2.d.ts","sourceRoot":"","sources":["../../src/lib/oauth2.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,oBAAoB,EACpB,gBAAgB,EAChB,uBAAuB,EACvB,WAAW,EACX,QAAQ,EACT,MAAM,YAAY,CAAC;AAEpB,MAAM,WAAW,aAAa;IAC5B,gBAAgB,EAAE,MAAM,CAAC;IACzB,QAAQ,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,eAAe,EAAE,MAAM,EAAE,CAAC;IAC1B,0EAA0E;IAC1E,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,oFAAoF;IACpF,mBAAmB,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC7C,qEAAqE;IACrE,YAAY,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IAC/B,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,mEAAmE;IACnE,qBAAqB,CAAC,CAAC,IAAI,EAAE,oBAAoB,GAAG,MAAM,CAAC;IAC3D,YAAY,CAAC,CAAC,IAAI,EAAE,gBAAgB,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IACzD,OAAO,CAAC,CAAC,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;IAC/C,+DAA+D;IAC/D,kBAAkB,CAAC,CAAC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,CAAC;CAC9D;AAED,qBAAa,WAAY,SAAQ,KAAK;gBACxB,OAAO,EAAE,MAAM;CAI5B;AAED;;;GAGG;AACH,wBAAgB,MAAM,CAAC,OAAO,EAAE,aAAa,GAAG,uBAAuB,CAoGtE;AAqBD,kDAAkD;AAClD,wBAAgB,aAAa,CAAC,QAAQ,EAAE,MAAM,GAAG,MAAM,CAEtD;AAED;;;GAGG;AACH,wBAAgB,oBAAoB,IAAI,MAAM,CAE7C"}

package/dist/lib/oauth2.js

@@ -0,0 +1,113 @@
+import { createHash, randomBytes } from 'node:crypto';
+export class OAuth2Error extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'OAuth2Error';
+    }
+}
+/**
+ * A complete OAuth2 authorization-code implementation. An integration supplies
+ * endpoints and scopes; this handles the redirect, the exchange, and refresh.
+ */
+export function oauth2(options) {
+    const separator = options.scopeSeparator ?? ' ';
+    const tokenRequest = options.tokenRequest ?? 'form';
+    const pkce = options.pkce ?? false;
+    const parseTokenResponse = options.parseTokenResponse ?? defaultParseTokenResponse;
+    const buildAuthorizationUrl = (args) => {
+        const url = new URL(options.authorizationUrl);
+        url.searchParams.set('response_type', 'code');
+        url.searchParams.set('client_id', args.client.clientId);
+        url.searchParams.set('redirect_uri', args.client.redirectUri);
+        url.searchParams.set('state', args.state);
+        if (args.client.scopes.length > 0) {
+            url.searchParams.set('scope', args.client.scopes.join(separator));
+        }
+        for (const [key, value] of Object.entries(options.authorizationParams ?? {})) {
+            url.searchParams.set(key, value);
+        }
+        if (pkce) {
+            if (!args.codeVerifier) {
+                throw new OAuth2Error('PKCE is enabled for this integration but no code verifier was provided');
+            }
+            // The challenge is the hash of the verifier, never the verifier itself —
+            // sending the verifier here would defeat the point of PKCE.
+            url.searchParams.set('code_challenge', s256Challenge(args.codeVerifier));
+            url.searchParams.set('code_challenge_method', 'S256');
+        }
+        return url.toString();
+    };
+    const postToken = async (params) => {
+        const response = await fetch(options.tokenUrl, {
+            method: 'POST',
+            headers: {
+                Accept: 'application/json',
+                'Content-Type': tokenRequest === 'json'
+                    ? 'application/json'
+                    : 'application/x-www-form-urlencoded',
+            },
+            body: tokenRequest === 'json'
+                ? JSON.stringify(params)
+                : new URLSearchParams(params).toString(),
+        });
+        const body = (await response.json().catch(() => null));
+        if (!response.ok || !body || body['error']) {
+            const detail = body?.['error_description'] ??
+                body?.['error'] ??
+                `HTTP ${response.status}`;
+            throw new OAuth2Error(`Token request failed: ${detail}`);
+        }
+        return parseTokenResponse(body);
+    };
+    return {
+        type: 'OAUTH2',
+        authorizationUrl: options.authorizationUrl,
+        tokenUrl: options.tokenUrl,
+        revokeUrl: options.revokeUrl,
+        scopesAvailable: options.scopesAvailable,
+        pkce,
+        buildAuthorizationUrl: options.buildAuthorizationUrl ?? buildAuthorizationUrl,
+        exchangeCode: options.exchangeCode ??
+            (({ client, code, codeVerifier }) => postToken({
+                grant_type: 'authorization_code',
+                client_id: client.clientId,
+                client_secret: client.clientSecret,
+                redirect_uri: client.redirectUri,
+                code,
+                ...(codeVerifier ? { code_verifier: codeVerifier } : {}),
+            })),
+        refresh: options.refresh ??
+            (({ client, refreshToken }) => postToken({
+                grant_type: 'refresh_token',
+                client_id: client.clientId,
+                client_secret: client.clientSecret,
+                refresh_token: refreshToken,
+            })),
+    };
+}
+function defaultParseTokenResponse(body) {
+    const accessToken = body['access_token'];
+    if (typeof accessToken !== 'string') {
+        throw new OAuth2Error('Token response contained no access_token');
+    }
+    return {
+        accessToken,
+        refreshToken: typeof body['refresh_token'] === 'string'
+            ? body['refresh_token']
+            : undefined,
+        tokenType: typeof body['token_type'] === 'string' ? body['token_type'] : undefined,
+        expiresInSeconds: typeof body['expires_in'] === 'number' ? body['expires_in'] : undefined,
+        raw: body,
+    };
+}
+/** RFC 7636 S256: base64url(sha256(verifier)). */
+export function s256Challenge(verifier) {
+    return createHash('sha256').update(verifier).digest('base64url');
+}
+/**
+ * A PKCE code verifier: 43-128 unreserved characters. base64url of 32 random
+ * bytes lands at 43.
+ */
+export function generateCodeVerifier() {
+    return randomBytes(32).toString('base64url');
+}

package/dist/lib/types.d.ts

@@ -0,0 +1,141 @@
+/**
+ * The integration contract. An integration package exports a factory that
+ * returns one {@link KoshaIntegration}; the server loads it at boot, syncs it
+ * into the provider catalogue, and resolves it per request.
+ */
+export type KoshaAuthType = 'OAUTH2' | 'OAUTH1' | 'API_KEY' | 'BASIC' | 'CUSTOM';
+/**
+ * One organization's resolved credentials for a provider — comes from the
+ * `configuration` row, never from the integration package itself.
+ */
+export interface OAuthClientContext {
+    clientId: string;
+    clientSecret: string;
+    redirectUri: string;
+    scopes: string[];
+}
+export interface TokenSet {
+    accessToken: string;
+    refreshToken?: string;
+    tokenType?: string;
+    expiresInSeconds?: number;
+    /** Provider's untouched response, for debugging. Never logged. */
+    raw?: unknown;
+}
+export interface Credential {
+    accessToken: string;
+    tokenType?: string | null;
+}
+export interface AccountIdentity {
+    externalAccountId: string;
+    label?: string;
+}
+/** Minimal HTTP client handed to integrations, pre-bound to `api.baseUrl`. */
+export interface IntegrationHttp {
+    get<T = unknown>(path: string, init?: IntegrationRequestInit): Promise<T>;
+    post<T = unknown>(path: string, init?: IntegrationRequestInit): Promise<T>;
+    request<T = unknown>(path: string, init?: IntegrationRequestInit): Promise<T>;
+}
+export interface IntegrationRequestInit {
+    method?: string;
+    accessToken?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    query?: Record<string, string | number | boolean | undefined>;
+}
+export interface AuthorizationUrlArgs {
+    client: OAuthClientContext;
+    state: string;
+    /** PKCE verifier, generated by the server when `pkce` is enabled. */
+    codeVerifier?: string;
+}
+export interface ExchangeCodeArgs {
+    client: OAuthClientContext;
+    code: string;
+    codeVerifier?: string;
+}
+export interface RefreshArgs {
+    client: OAuthClientContext;
+    refreshToken: string;
+}
+/**
+ * How an integration authenticates. `oauth2()` provides a complete
+ * implementation; any step can be replaced for a provider that deviates.
+ */
+export interface IntegrationAuthStrategy {
+    type: KoshaAuthType;
+    authorizationUrl?: string;
+    tokenUrl?: string;
+    revokeUrl?: string;
+    scopesAvailable: string[];
+    pkce: boolean;
+    buildAuthorizationUrl(args: AuthorizationUrlArgs): string;
+    exchangeCode(args: ExchangeCodeArgs): Promise<TokenSet>;
+    refresh?(args: RefreshArgs): Promise<TokenSet>;
+}
+export interface IntegrationApi {
+    /** Base URL the proxy forwards requests to. */
+    baseUrl: string;
+    /** Headers that authenticate a proxied request. */
+    authHeaders(credential: Credential): Record<string, string>;
+}
+export interface IntegrationIdentity {
+    fetchAccount(args: {
+        accessToken: string;
+        http: IntegrationHttp;
+    }): Promise<AccountIdentity>;
+}
+/**
+ * Per-organization settings, described well enough for the admin to render a
+ * form without shipping any integration-specific UI code.
+ */
+export interface IntegrationConfigField {
+    key: string;
+    label: string;
+    type: 'string' | 'number' | 'boolean' | 'select';
+    required?: boolean;
+    secret?: boolean;
+    options?: {
+        label: string;
+        value: string;
+    }[];
+    help?: string;
+}
+export interface IntegrationWebhooks {
+    /** Verify the provider's signature. Returning false rejects the delivery. */
+    verify(args: {
+        body: string;
+        headers: Record<string, string | string[] | undefined>;
+        secret?: string;
+    }): boolean | Promise<boolean>;
+    handle(args: {
+        payload: unknown;
+        organizationId: string;
+    }): Promise<void>;
+}
+export interface IntegrationHooks {
+    onConnectionCreated?(args: {
+        connectionId: string;
+        organizationId: string;
+    }): Promise<void> | void;
+    onTokenRefreshed?(args: {
+        connectionId: string;
+        tokens: TokenSet;
+    }): Promise<void> | void;
+}
+export interface KoshaIntegration {
+    /** Stable identifier; the primary key in the provider catalogue. */
+    key: string;
+    name: string;
+    logo?: string;
+    docsUrl?: string;
+    auth: IntegrationAuthStrategy;
+    api: IntegrationApi;
+    identity: IntegrationIdentity;
+    configFields?: IntegrationConfigField[];
+    webhooks?: IntegrationWebhooks;
+    hooks?: IntegrationHooks;
+}
+/** What an integration package's default export is. */
+export type IntegrationFactory<TOptions = void> = TOptions extends void ? () => KoshaIntegration : (options?: TOptions) => KoshaIntegration;
+//# sourceMappingURL=types.d.ts.map

package/dist/lib/types.d.ts.map

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

package/dist/lib/types.js

@@ -0,0 +1,6 @@
+/**
+ * The integration contract. An integration package exports a factory that
+ * returns one {@link KoshaIntegration}; the server loads it at boot, syncs it
+ * into the provider catalogue, and resolves it per request.
+ */
+export {};

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@kosha-ai/integration-sdk",
+  "version": "0.0.1",
+  "description": "SDK for authoring Kosha integrations",
+  "keywords": [
+    "kosha",
+    "sdk",
+    "oauth",
+    "integrations"
+  ],
+  "license": "MIT",
+  "homepage": "https://github.com/codemancers/kosha#readme",
+  "bugs": {
+    "url": "https://github.com/codemancers/kosha/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/codemancers/kosha.git",
+    "directory": "packages/integration-sdk"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "@org/source": "./src/index.ts",
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "!**/*.tsbuildinfo"
+  ],
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}