@onkernel/sdk 0.1.0-alpha.1 → 0.1.0-alpha.11

package/resources/index.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/resources/index.ts"],"names":[],"mappings":"OAEO,EACL,IAAI,EACJ,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,6BAA6B,EAClC,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB;OACM,EAAE,OAAO,EAAE,KAAK,4BAA4B,EAAE"}
+{"version":3,"file":"index.d.mts","sourceRoot":"","sources":["../src/resources/index.ts"],"names":[],"mappings":"OAEO,EAAE,IAAI,EAAE;OACR,EACL,QAAQ,EACR,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,GACzB"}

package/resources/index.d.ts

@@ -1,3 +1,3 @@
-export { Apps, type AppDeployResponse, type AppInvokeResponse, type AppRetrieveInvocationResponse, type AppDeployParams, type AppInvokeParams, } from "./apps.js";
-export { Browser, type BrowserCreateSessionResponse } from "./browser.js";
+export { Apps } from "./apps/apps.js";
+export { Browsers, type BrowserCreateResponse, type BrowserRetrieveResponse, type BrowserCreateParams, } from "./browsers.js";
 //# sourceMappingURL=index.d.ts.map

package/resources/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/resources/index.ts"],"names":[],"mappings":"OAEO,EACL,IAAI,EACJ,KAAK,iBAAiB,EACtB,KAAK,iBAAiB,EACtB,KAAK,6BAA6B,EAClC,KAAK,eAAe,EACpB,KAAK,eAAe,GACrB;OACM,EAAE,OAAO,EAAE,KAAK,4BAA4B,EAAE"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/resources/index.ts"],"names":[],"mappings":"OAEO,EAAE,IAAI,EAAE;OACR,EACL,QAAQ,EACR,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,EAC5B,KAAK,mBAAmB,GACzB"}

package/resources/index.js

@@ -1,9 +1,9 @@
 "use strict";
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Browser = exports.Apps = void 0;
-var apps_1 = require("./apps.js");
+exports.Browsers = exports.Apps = void 0;
+var apps_1 = require("./apps/apps.js");
 Object.defineProperty(exports, "Apps", { enumerable: true, get: function () { return apps_1.Apps; } });
-var browser_1 = require("./browser.js");
-Object.defineProperty(exports, "Browser", { enumerable: true, get: function () { return browser_1.Browser; } });
+var browsers_1 = require("./browsers.js");
+Object.defineProperty(exports, "Browsers", { enumerable: true, get: function () { return browsers_1.Browsers; } });
 //# sourceMappingURL=index.js.map

package/resources/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/resources/index.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kCAOgB;AANd,4FAAA,IAAI,OAAA;AAON,wCAAuE;AAA9D,kGAAA,OAAO,OAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/resources/index.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,uCAAmC;AAA1B,4FAAA,IAAI,OAAA;AACb,0CAKoB;AAJlB,oGAAA,QAAQ,OAAA"}

package/resources/index.mjs

@@ -1,4 +1,4 @@
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-export { Apps, } from "./apps.mjs";
-export { Browser } from "./browser.mjs";
+export { Apps } from "./apps/apps.mjs";
+export { Browsers, } from "./browsers.mjs";
 //# sourceMappingURL=index.mjs.map

package/resources/index.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/resources/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EACL,IAAI,GAML;OACM,EAAE,OAAO,EAAqC"}
+{"version":3,"file":"index.mjs","sourceRoot":"","sources":["../src/resources/index.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,IAAI,EAAE;OACR,EACL,QAAQ,GAIT"}

package/src/client.ts

@@ -21,17 +21,22 @@ import { type Fetch } from './internal/builtin-types';
 import { HeadersLike, NullableHeaders, buildHeaders } from './internal/headers';
 import { FinalRequestOptions, RequestOptions } from './internal/request-options';
 import {
-  AppDeployParams,
-  AppDeployResponse,
-  AppInvokeParams,
-  AppInvokeResponse,
-  AppRetrieveInvocationResponse,
-  Apps,
-} from './resources/apps';
-import { Browser, BrowserCreateSessionResponse } from './resources/browser';
+  BrowserCreateParams,
+  BrowserCreateResponse,
+  BrowserRetrieveResponse,
+  Browsers,
+} from './resources/browsers';
 import { readEnv } from './internal/utils/env';
 import { formatRequestDetails, loggerFor } from './internal/utils/log';
 import { isEmptyObj } from './internal/utils/values';
+import { KernelApp } from './core/app-framework';
+import { Apps } from './resources/apps/apps';
+
+const environments = {
+  production: 'https://api.onkernel.com/',
+  development: 'https://localhost:3001/',
+};
+type Environment = keyof typeof environments;
 
 export interface ClientOptions {
   /**
@@ -39,6 +44,15 @@ export interface ClientOptions {
    */
   apiKey?: string | undefined;
 
+  /**
+   * Specifies the environment to use for the API.
+   *
+   * Each environment maps to a different base URL:
+   * - `production` corresponds to `https://api.onkernel.com/`
+   * - `development` corresponds to `https://localhost:3001/`
+   */
+  environment?: Environment | undefined;
+
   /**
    * Override the default base URL for the API, e.g., "https://api.example.com/v2/"
    *
@@ -128,7 +142,8 @@ export class Kernel {
    * API Client for interfacing with the Kernel API.
    *
    * @param {string | undefined} [opts.apiKey=process.env['KERNEL_API_KEY'] ?? undefined]
-   * @param {string} [opts.baseURL=process.env['KERNEL_BASE_URL'] ?? http://localhost:3001] - Override the default base URL for the API.
+   * @param {Environment} [opts.environment=production] - Specifies the environment URL to use for the API.
+   * @param {string} [opts.baseURL=process.env['KERNEL_BASE_URL'] ?? https://api.onkernel.com/] - Override the default base URL for the API.
    * @param {number} [opts.timeout=1 minute] - The maximum amount of time (in milliseconds) the client will wait for a response before timing out.
    * @param {MergedRequestInit} [opts.fetchOptions] - Additional `RequestInit` options to be passed to `fetch` calls.
    * @param {Fetch} [opts.fetch] - Specify a custom `fetch` function implementation.
@@ -150,10 +165,17 @@ export class Kernel {
     const options: ClientOptions = {
       apiKey,
       ...opts,
-      baseURL: baseURL || `http://localhost:3001`,
+      baseURL,
+      environment: opts.environment ?? 'production',
     };
 
-    this.baseURL = options.baseURL!;
+    if (baseURL && opts.environment) {
+      throw new Errors.KernelError(
+        'Ambiguous URL; The `baseURL` option (or KERNEL_BASE_URL env var) and the `environment` option are given. If you want to use the environment you must pass baseURL: null',
+      );
+    }
+
+    this.baseURL = options.baseURL || environments[options.environment || 'production'];
     this.timeout = options.timeout ?? Kernel.DEFAULT_TIMEOUT /* 1 minute */;
     this.logger = options.logger ?? console;
     const defaultLogLevel = 'warn';
@@ -179,7 +201,8 @@ export class Kernel {
   withOptions(options: Partial<ClientOptions>): this {
     return new (this.constructor as any as new (props: ClientOptions) => typeof this)({
       ...this._options,
-      baseURL: this.baseURL,
+      environment: options.environment ? options.environment : undefined,
+      baseURL: options.environment ? undefined : this.baseURL,
       maxRetries: this.maxRetries,
       timeout: this.timeout,
       logger: this.logger,
@@ -680,6 +703,16 @@ export class Kernel {
     }
   }
 
+  /**
+   * Create a new KernelApp instance.
+   *
+   * @param name - The name of the app to create.
+   * @returns A new KernelApp instance you can attach actions to.
+   */
+  public app(name: string): KernelApp {
+    return new KernelApp(name);
+  }
+
   static Kernel = this;
   static DEFAULT_TIMEOUT = 60000; // 1 minute
 
@@ -700,21 +733,19 @@ export class Kernel {
   static toFile = Uploads.toFile;
 
   apps: API.Apps = new API.Apps(this);
-  browser: API.Browser = new API.Browser(this);
+  browsers: API.Browsers = new API.Browsers(this);
 }
 Kernel.Apps = Apps;
-Kernel.Browser = Browser;
+Kernel.Browsers = Browsers;
 export declare namespace Kernel {
   export type RequestOptions = Opts.RequestOptions;
 
+  export { Apps as Apps };
+
   export {
-    Apps as Apps,
-    type AppDeployResponse as AppDeployResponse,
-    type AppInvokeResponse as AppInvokeResponse,
-    type AppRetrieveInvocationResponse as AppRetrieveInvocationResponse,
-    type AppDeployParams as AppDeployParams,
-    type AppInvokeParams as AppInvokeParams,
+    Browsers as Browsers,
+    type BrowserCreateResponse as BrowserCreateResponse,
+    type BrowserRetrieveResponse as BrowserRetrieveResponse,
+    type BrowserCreateParams as BrowserCreateParams,
   };
-
-  export { Browser as Browser, type BrowserCreateSessionResponse as BrowserCreateSessionResponse };
 }

package/src/core/app-framework.ts

@@ -0,0 +1,137 @@
+export interface KernelContext {
+  invocationId: string;
+}
+
+export interface KernelAction {
+  name: string;
+  handler: (context: KernelContext, input: any) => Promise<any>;
+}
+
+export interface KernelJson {
+  apps: KernelAppJson[];
+}
+
+export interface KernelAppJson {
+  name: string;
+  actions: KernelActionJson[];
+}
+
+export interface KernelActionJson {
+  name: string;
+}
+
+export class KernelApp {
+  name: string;
+  actions: Map<string, KernelAction> = new Map();
+
+  constructor(name: string) {
+    this.name = name;
+    // Register this app in the global registry
+    appRegistry.registerApp(this);
+  }
+
+  /**
+   * Define an action
+   */
+  action<T, R>(
+    nameOrHandler: string | ((input: T) => Promise<R>) | ((context: KernelContext, input: T) => Promise<R>),
+    handler?: ((input: T) => Promise<R>) | ((context: KernelContext, input: T) => Promise<R>),
+  ) {
+    let actionName: string;
+    let actionHandler: (context: KernelContext, input: T) => Promise<R>;
+
+    if (typeof nameOrHandler === 'string' && handler) {
+      // Case: app.action("name", handler)
+      actionName = nameOrHandler;
+
+      // Create a handler that accepts context and input, adapting if needed
+      if (handler.length === 1) {
+        // Original handler only takes input, so we adapt it to the new signature
+        const singleArgHandler = handler as (input: T) => Promise<R>;
+        actionHandler = async (context: KernelContext, input: T) => singleArgHandler(input);
+      } else {
+        // Handler takes both context and input
+        actionHandler = handler as (context: KernelContext, input: T) => Promise<R>;
+      }
+    } else if (typeof nameOrHandler === 'function') {
+      // Case: app.action(handler)
+      actionName = nameOrHandler.name || 'default';
+
+      // Create a handler that accepts context and input, adapting if needed
+      if (nameOrHandler.length === 1) {
+        // Original handler only takes input, so we adapt it to the new signature
+        const singleArgHandler = nameOrHandler as (input: T) => Promise<R>;
+        actionHandler = async (context: KernelContext, input: T) => singleArgHandler(input);
+      } else {
+        // Handler takes both context and input
+        actionHandler = nameOrHandler as (context: KernelContext, input: T) => Promise<R>;
+      }
+    } else {
+      throw new Error('Invalid action definition');
+    }
+
+    // Register the action
+    this.actions.set(actionName, {
+      name: actionName,
+      handler: actionHandler,
+    });
+
+    return actionHandler;
+  }
+
+  /**
+   * Get all actions for this app
+   */
+  getActions(): KernelAction[] {
+    return Array.from(this.actions.values());
+  }
+
+  /**
+   * Get an action by name
+   */
+  getAction(name: string): KernelAction | undefined {
+    return this.actions.get(name);
+  }
+
+  /**
+   * Export app information without handlers
+   */
+  toJSON(): KernelAppJson {
+    return {
+      name: this.name,
+      actions: this.getActions().map((action) => ({
+        name: action.name,
+      })),
+    };
+  }
+}
+
+// Registry for storing all Kernel apps
+class KernelAppRegistry {
+  private apps: Map<string, KernelApp> = new Map();
+
+  registerApp(app: KernelApp): void {
+    this.apps.set(app.name, app);
+  }
+
+  getApps(): KernelApp[] {
+    return Array.from(this.apps.values());
+  }
+
+  getAppByName(name: string): KernelApp | undefined {
+    return this.apps.get(name);
+  }
+
+  export(): KernelJson {
+    return {
+      apps: this.getApps().map((app) => app.toJSON()),
+    };
+  }
+
+  exportJSON(): string {
+    return JSON.stringify(this.export(), null, 2);
+  }
+}
+
+// Create a singleton registry for apps
+export const appRegistry = new KernelAppRegistry();

package/src/index.ts

@@ -20,3 +20,5 @@ export {
   PermissionDeniedError,
   UnprocessableEntityError,
 } from './core/error';
+
+export { KernelAction, KernelContext, KernelJson, appRegistry } from './core/app-framework';

package/src/internal/headers.ts

@@ -71,8 +71,8 @@ function* iterateHeaders(headers: HeadersLike): IterableIterator<readonly [strin
 export const buildHeaders = (newHeaders: HeadersLike[]): NullableHeaders => {
   const targetHeaders = new Headers();
   const nullHeaders = new Set<string>();
-  const seenHeaders = new Set<string>();
   for (const headers of newHeaders) {
+    const seenHeaders = new Set<string>();
     for (const [name, value] of iterateHeaders(headers)) {
       const lowerName = name.toLowerCase();
       if (!seenHeaders.has(lowerName)) {

package/src/resources/apps/apps.ts

@@ -0,0 +1,35 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import * as DeploymentsAPI from './deployments';
+import { DeploymentCreateParams, DeploymentCreateResponse, Deployments } from './deployments';
+import * as InvocationsAPI from './invocations';
+import {
+  InvocationCreateParams,
+  InvocationCreateResponse,
+  InvocationRetrieveResponse,
+  Invocations,
+} from './invocations';
+
+export class Apps extends APIResource {
+  deployments: DeploymentsAPI.Deployments = new DeploymentsAPI.Deployments(this._client);
+  invocations: InvocationsAPI.Invocations = new InvocationsAPI.Invocations(this._client);
+}
+
+Apps.Deployments = Deployments;
+Apps.Invocations = Invocations;
+
+export declare namespace Apps {
+  export {
+    Deployments as Deployments,
+    type DeploymentCreateResponse as DeploymentCreateResponse,
+    type DeploymentCreateParams as DeploymentCreateParams,
+  };
+
+  export {
+    Invocations as Invocations,
+    type InvocationCreateResponse as InvocationCreateResponse,
+    type InvocationRetrieveResponse as InvocationRetrieveResponse,
+    type InvocationCreateParams as InvocationCreateParams,
+  };
+}

package/src/resources/apps/deployments.ts

@@ -0,0 +1,103 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { type Uploadable } from '../../core/uploads';
+import { RequestOptions } from '../../internal/request-options';
+import { multipartFormRequestOptions } from '../../internal/uploads';
+
+export class Deployments extends APIResource {
+  /**
+   * Deploy a new application
+   *
+   * @example
+   * ```ts
+   * const deployment = await client.apps.deployments.create({
+   *   entrypoint_rel_path: 'src/app.py',
+   *   file: fs.createReadStream('path/to/file'),
+   * });
+   * ```
+   */
+  create(body: DeploymentCreateParams, options?: RequestOptions): APIPromise<DeploymentCreateResponse> {
+    return this._client.post('/deploy', multipartFormRequestOptions({ body, ...options }, this._client));
+  }
+}
+
+export interface DeploymentCreateResponse {
+  /**
+   * List of apps deployed
+   */
+  apps: Array<DeploymentCreateResponse.App>;
+
+  /**
+   * Current status of the deployment
+   */
+  status: 'queued' | 'deploying' | 'succeeded' | 'failed';
+
+  /**
+   * Status reason
+   */
+  status_reason?: string;
+}
+
+export namespace DeploymentCreateResponse {
+  export interface App {
+    /**
+     * ID for the app version deployed
+     */
+    id: string;
+
+    /**
+     * List of actions available on the app
+     */
+    actions: Array<App.Action>;
+
+    /**
+     * Name of the app
+     */
+    name: string;
+  }
+
+  export namespace App {
+    export interface Action {
+      /**
+       * Name of the action
+       */
+      name: string;
+    }
+  }
+}
+
+export interface DeploymentCreateParams {
+  /**
+   * Relative path to the entrypoint of the application
+   */
+  entrypoint_rel_path: string;
+
+  /**
+   * ZIP file containing the application source directory
+   */
+  file: Uploadable;
+
+  /**
+   * Allow overwriting an existing app version
+   */
+  force?: boolean;
+
+  /**
+   * Region for deployment. Currently we only support "aws.us-east-1a"
+   */
+  region?: 'aws.us-east-1a';
+
+  /**
+   * Version of the application. Can be any string.
+   */
+  version?: string;
+}
+
+export declare namespace Deployments {
+  export {
+    type DeploymentCreateResponse as DeploymentCreateResponse,
+    type DeploymentCreateParams as DeploymentCreateParams,
+  };
+}

package/src/resources/apps/index.ts

@@ -0,0 +1,10 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+export { Apps } from './apps';
+export { Deployments, type DeploymentCreateResponse, type DeploymentCreateParams } from './deployments';
+export {
+  Invocations,
+  type InvocationCreateResponse,
+  type InvocationRetrieveResponse,
+  type InvocationCreateParams,
+} from './invocations';

package/src/resources/apps/invocations.ts

@@ -0,0 +1,140 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+
+import { APIResource } from '../../core/resource';
+import { APIPromise } from '../../core/api-promise';
+import { RequestOptions } from '../../internal/request-options';
+import { path } from '../../internal/utils/path';
+
+export class Invocations extends APIResource {
+  /**
+   * Invoke an application
+   *
+   * @example
+   * ```ts
+   * const invocation = await client.apps.invocations.create({
+   *   action_name: 'analyze',
+   *   app_name: 'my-app',
+   *   version: '1.0.0',
+   * });
+   * ```
+   */
+  create(body: InvocationCreateParams, options?: RequestOptions): APIPromise<InvocationCreateResponse> {
+    return this._client.post('/invocations', { body, ...options });
+  }
+
+  /**
+   * Get an app invocation by id
+   *
+   * @example
+   * ```ts
+   * const invocation = await client.apps.invocations.retrieve(
+   *   'ckqwer3o20000jb9s7abcdef',
+   * );
+   * ```
+   */
+  retrieve(id: string, options?: RequestOptions): APIPromise<InvocationRetrieveResponse> {
+    return this._client.get(path`/invocations/${id}`, options);
+  }
+}
+
+export interface InvocationCreateResponse {
+  /**
+   * ID of the invocation
+   */
+  id: string;
+
+  /**
+   * Status of the invocation
+   */
+  status: 'queued' | 'running' | 'succeeded' | 'failed';
+
+  /**
+   * The return value of the action that was invoked, rendered as a JSON string. This
+   * could be: string, number, boolean, array, object, or null.
+   */
+  output?: string;
+
+  /**
+   * Status reason
+   */
+  status_reason?: string;
+}
+
+export interface InvocationRetrieveResponse {
+  /**
+   * ID of the invocation
+   */
+  id: string;
+
+  /**
+   * Name of the action invoked
+   */
+  action_name: string;
+
+  /**
+   * Name of the application
+   */
+  app_name: string;
+
+  /**
+   * RFC 3339 Nanoseconds timestamp when the invocation started
+   */
+  started_at: string;
+
+  /**
+   * Status of the invocation
+   */
+  status: 'queued' | 'running' | 'succeeded' | 'failed';
+
+  /**
+   * RFC 3339 Nanoseconds timestamp when the invocation finished (null if still
+   * running)
+   */
+  finished_at?: string | null;
+
+  /**
+   * Output produced by the action, rendered as a JSON string. This could be: string,
+   * number, boolean, array, object, or null.
+   */
+  output?: string;
+
+  /**
+   * Payload provided to the invocation. This is a string that can be parsed as JSON.
+   */
+  payload?: string;
+
+  /**
+   * Status reason
+   */
+  status_reason?: string;
+}
+
+export interface InvocationCreateParams {
+  /**
+   * Name of the action to invoke
+   */
+  action_name: string;
+
+  /**
+   * Name of the application
+   */
+  app_name: string;
+
+  /**
+   * Version of the application
+   */
+  version: string;
+
+  /**
+   * Input data for the action, sent as a JSON string.
+   */
+  payload?: string;
+}
+
+export declare namespace Invocations {
+  export {
+    type InvocationCreateResponse as InvocationCreateResponse,
+    type InvocationRetrieveResponse as InvocationRetrieveResponse,
+    type InvocationCreateParams as InvocationCreateParams,
+  };
+}