Expand API SDK surface

Author: nmharmon8

README.md

@@ -58,7 +58,7 @@ const project = await client.createProject({
 
 const generation = await client.createGeneration({
   apiProjectId: project.apiProjectId,
-  model: "diffio-2",
+  model: "diffio-3.5",
   sampling: { steps: 12, guidance: 1.5 }
 });
 
@@ -73,7 +73,7 @@ import { DiffioClient } from "diffio";
 const client = new DiffioClient({ apiKey: "diffio_live_..." });
 const result = await client.audioIsolation.isolate({
   filePath: "sample.wav",
-  model: "diffio-2",
+  model: "diffio-3.5",
   sampling: { steps: 12, guidance: 1.5 }
 });
 
@@ -91,7 +91,7 @@ import { DiffioClient } from "diffio";
 const client = new DiffioClient({ apiKey: "diffio_live_..." });
 const [audioBytes, info] = await client.restoreAudio({
   filePath: "sample.wav",
-  model: "diffio-2",
+  model: "diffio-3.5",
   sampling: { steps: 12, guidance: 1.5 },
   onProgress: (progress) => console.log(progress.status)
 });
@@ -134,6 +134,35 @@ const download = await client.generations.getDownload({
 console.log(download.downloadUrl);
 ```
 
+Set `downloadType` to `"transcript"` to fetch the transcript JSON artifact when the generation has one.
+
+```ts
+const transcript = await client.generations.getDownload({
+  generationId: "gen_123",
+  apiProjectId: "proj_123",
+  downloadType: "transcript"
+});
+```
+
+## Account, keys, usage, and webhook configuration
+
+Agent keys can manage account settings, scoped keys, usage, and webhook endpoints.
+
+```ts
+const settings = await client.account.getSettings();
+const key = await client.apiKeys.create({
+  label: "Backend worker",
+  scopes: ["projects:read", "projects:write", "generations:read", "generations:write", "artifacts:read"]
+});
+const usage = await client.usage.summary({ apiKeyId: key.keyId });
+const webhook = await client.webhooks.configure({
+  mode: "live",
+  url: "https://example.com/webhooks/diffio",
+  eventTypes: ["generation.completed", "generation.failed"],
+  apiKeyId: key.keyId
+});
+```
+
 ## List projects
 
 ```ts

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "diffio",
-  "version": "0.1.3",
+  "version": "0.1.7",
   "description": "Diffio API client for Node.js",
   "repository": {
     "type": "git",

package.json

@@ -7,15 +7,23 @@ import { requestWithRetries } from "./core/retry";
 import { DiffioApiError, DiffioTimeoutError } from "./errors";
 import {
   createAudioIsolationResult,
+  parseAccountSettingsResponse,
+  parseApiKeyResponse,
+  parseApiKeysListResponse,
   parseCreateGenerationResponse,
   parseCreateProjectResponse,
   parseGenerationDownloadResponse,
   parseGenerationProgressResponse,
   parseListProjectGenerationsResponse,
   parseListProjectsResponse,
+  parseUsageSummaryResponse,
+  parseWebhookConfigureResponse,
   parseWebhookTestEventResponse
 } from "./api/serialization";
 import type {
+  AccountSettingsResponse,
+  ApiKeyResponse,
+  ApiKeysListResponse,
   AudioIsolationResult,
   CreateGenerationResponse,
   CreateProjectResponse,
@@ -24,17 +32,29 @@ import type {
   ListProjectGenerationsResponse,
   ListProjectsResponse,
   RestoreMetadata,
+  UsageSummaryResponse,
+  WebhookConfigureResponse,
   WebhookTestEventResponse
 } from "./api/types";
-import { AudioIsolationClient, GenerationsClient, ProjectsClient, WebhooksClient } from "./api/resources";
+import {
+  AccountClient,
+  ApiKeysClient,
+  AudioIsolationClient,
+  GenerationsClient,
+  ProjectsClient,
+  UsageClient,
+  WebhooksClient
+} from "./api/resources";
 import { lookup as lookupMimeType } from "mime-types";
 
 const DEFAULT_BASE_URL = "https://api.diffio.ai";
 const API_PREFIX = "v1";
 const MODEL_ENDPOINTS: Record<string, string> = {
   "diffio-2": "diffio-2.0-generation",
   "diffio-2-flash": "diffio-2.0-flash-generation",
-  "diffio-3": "diffio-3.0-generation"
+  "diffio-3": "diffio-3.0-generation",
+  "diffio-3.4": "diffio-3.4-generation",
+  "diffio-3.5": "diffio-3.5-generation"
 };
 const DEFAULT_RETRY_STATUS_CODES = [408, 429, 500, 502, 503, 504];
 const DEFAULT_RETRY_BACKOFF = 0.5;
@@ -58,6 +78,9 @@ export class DiffioClient {
   public readonly audioIsolation: AudioIsolationClient;
   public readonly generations: GenerationsClient;
   public readonly projects: ProjectsClient;
+  public readonly account: AccountClient;
+  public readonly apiKeys: ApiKeysClient;
+  public readonly usage: UsageClient;
   public readonly webhooks: WebhooksClient;
 
   constructor(options: DiffioClient.Options = {}) {
@@ -71,6 +94,9 @@ export class DiffioClient {
     this.audioIsolation = new AudioIsolationClient(this);
     this.generations = new GenerationsClient(this);
     this.projects = new ProjectsClient(this);
+    this.account = new AccountClient(this);
+    this.apiKeys = new ApiKeysClient(this);
+    this.usage = new UsageClient(this);
     this.webhooks = new WebhooksClient(this);
   }
 
@@ -279,15 +305,122 @@ export class DiffioClient {
     const { generationId, apiProjectId, downloadType, requestOptions } = options;
     const payload: Record<string, unknown> = { generationId, apiProjectId };
     if (downloadType != null) {
-      if (downloadType !== "audio" && downloadType !== "video") {
-        throw new DiffioApiError("downloadType must be audio or video");
+      if (downloadType !== "audio" && downloadType !== "video" && downloadType !== "transcript") {
+        throw new DiffioApiError("downloadType must be audio, video, or transcript");
       }
       payload.downloadType = downloadType;
     }
     const response = await this._requestJson("POST", "get_generation_download", payload, requestOptions);
     return parseGenerationDownloadResponse(response);
   }
 
+  async getAccountSettings(options: {
+    requestOptions?: DiffioClient.RequestOptions;
+  } = {}): Promise<AccountSettingsResponse> {
+    const response = await this._requestJson("POST", "account/settings/get", {}, options.requestOptions);
+    return parseAccountSettingsResponse(response);
+  }
+
+  async updateAccountSettings(options: {
+    billingPolicy: Record<string, unknown>;
+    requestOptions?: DiffioClient.RequestOptions;
+  }): Promise<AccountSettingsResponse> {
+    const { billingPolicy, requestOptions } = options;
+    if (!billingPolicy || typeof billingPolicy !== "object" || Array.isArray(billingPolicy)) {
+      throw new DiffioApiError("billingPolicy must be an object");
+    }
+    const response = await this._requestJson("POST", "account/settings/update", { billingPolicy }, requestOptions);
+    return parseAccountSettingsResponse(response);
+  }
+
+  async createApiKey(options: {
+    label: string;
+    scopes: string[];
+    resourceBounds?: Record<string, unknown>;
+    requestOptions?: DiffioClient.RequestOptions;
+  }): Promise<ApiKeyResponse> {
+    const { label, scopes, resourceBounds, requestOptions } = options;
+    if (!label) {
+      throw new DiffioApiError("label is required");
+    }
+    if (!Array.isArray(scopes)) {
+      throw new DiffioApiError("scopes must be an array");
+    }
+    const response = await this._requestJson(
+      "POST",
+      "api_keys/create",
+      { label, scopes, resourceBounds: resourceBounds ?? {} },
+      requestOptions
+    );
+    return parseApiKeyResponse(response);
+  }
+
+  async listApiKeys(options: { requestOptions?: DiffioClient.RequestOptions } = {}): Promise<ApiKeysListResponse> {
+    const response = await this._requestJson("POST", "api_keys/list", {}, options.requestOptions);
+    return parseApiKeysListResponse(response);
+  }
+
+  async rotateApiKey(options: {
+    keyId: string;
+    requestOptions?: DiffioClient.RequestOptions;
+  }): Promise<ApiKeyResponse> {
+    const { keyId, requestOptions } = options;
+    if (!keyId) {
+      throw new DiffioApiError("keyId is required");
+    }
+    const response = await this._requestJson("POST", "api_keys/rotate", { keyId }, requestOptions);
+    return parseApiKeyResponse(response);
+  }
+
+  async revokeApiKey(options: {
+    keyId: string;
+    requestOptions?: DiffioClient.RequestOptions;
+  }): Promise<ApiKeyResponse> {
+    const { keyId, requestOptions } = options;
+    if (!keyId) {
+      throw new DiffioApiError("keyId is required");
+    }
+    const response = await this._requestJson("POST", "api_keys/revoke", { keyId }, requestOptions);
+    return parseApiKeyResponse(response);
+  }
+
+  async getUsageSummary(options: {
+    apiKeyId?: string;
+    requestOptions?: DiffioClient.RequestOptions;
+  } = {}): Promise<UsageSummaryResponse> {
+    const payload: Record<string, unknown> = {};
+    if (options.apiKeyId != null) {
+      payload.apiKeyId = options.apiKeyId;
+    }
+    const response = await this._requestJson("POST", "usage/summary", payload, options.requestOptions);
+    return parseUsageSummaryResponse(response);
+  }
+
+  async configureWebhook(options: {
+    mode: string;
+    url: string;
+    eventTypes: string[];
+    apiKeyId?: string;
+    requestOptions?: DiffioClient.RequestOptions;
+  }): Promise<WebhookConfigureResponse> {
+    const { mode, url, eventTypes, apiKeyId, requestOptions } = options;
+    if (!WEBHOOK_MODES.includes(mode)) {
+      throw new DiffioApiError("mode must be test or live");
+    }
+    if (!url) {
+      throw new DiffioApiError("url is required");
+    }
+    if (!Array.isArray(eventTypes) || eventTypes.length === 0) {
+      throw new DiffioApiError("eventTypes must be a non-empty array");
+    }
+    const payload: Record<string, unknown> = { mode, url, eventTypes };
+    if (apiKeyId != null) {
+      payload.apiKeyId = apiKeyId;
+    }
+    const response = await this._requestJson("POST", "webhooks/configure", payload, requestOptions);
+    return parseWebhookConfigureResponse(response);
+  }
+
   async sendWebhookTestEvent(options: {
     eventType: string;
     mode: string;
@@ -817,7 +950,12 @@ function isNodeReadable(value: unknown): value is NodeJS.ReadableStream {
 
 async function createFileReadStream(filePath: string): Promise<NodeJS.ReadableStream> {
   const fs = await import("node:fs");
-  return fs.createReadStream(filePath);
+  const stream = fs.createReadStream(filePath);
+  await new Promise<void>((resolve, reject) => {
+    stream.once("open", () => resolve());
+    stream.once("error", reject);
+  });
+  return stream;
 }
 
 function getFileSize(filePath: string): number {

src/Client.ts

@@ -0,0 +1,27 @@
+import type { DiffioClient } from "../../../../Client";
+import type { AccountSettingsResponse } from "../../../types";
+
+export interface AccountGetSettingsOptions {
+  requestOptions?: DiffioClient.RequestOptions;
+}
+
+export interface AccountUpdateSettingsOptions {
+  billingPolicy: Record<string, unknown>;
+  requestOptions?: DiffioClient.RequestOptions;
+}
+
+export class AccountClient {
+  private _parent: DiffioClient;
+
+  constructor(parent: DiffioClient) {
+    this._parent = parent;
+  }
+
+  async getSettings(options: AccountGetSettingsOptions = {}): Promise<AccountSettingsResponse> {
+    return this._parent.getAccountSettings(options);
+  }
+
+  async updateSettings(options: AccountUpdateSettingsOptions): Promise<AccountSettingsResponse> {
+    return this._parent.updateAccountSettings(options);
+  }
+}

src/api/resources/account/client/Client.ts

@@ -0,0 +1,47 @@
+import type { DiffioClient } from "../../../../Client";
+import type { ApiKeyResponse, ApiKeysListResponse } from "../../../types";
+
+export interface ApiKeysCreateOptions {
+  label: string;
+  scopes: string[];
+  resourceBounds?: Record<string, unknown>;
+  requestOptions?: DiffioClient.RequestOptions;
+}
+
+export interface ApiKeysListOptions {
+  requestOptions?: DiffioClient.RequestOptions;
+}
+
+export interface ApiKeysRotateOptions {
+  keyId: string;
+  requestOptions?: DiffioClient.RequestOptions;
+}
+
+export interface ApiKeysRevokeOptions {
+  keyId: string;
+  requestOptions?: DiffioClient.RequestOptions;
+}
+
+export class ApiKeysClient {
+  private _parent: DiffioClient;
+
+  constructor(parent: DiffioClient) {
+    this._parent = parent;
+  }
+
+  async create(options: ApiKeysCreateOptions): Promise<ApiKeyResponse> {
+    return this._parent.createApiKey(options);
+  }
+
+  async list(options: ApiKeysListOptions = {}): Promise<ApiKeysListResponse> {
+    return this._parent.listApiKeys(options);
+  }
+
+  async rotate(options: ApiKeysRotateOptions): Promise<ApiKeyResponse> {
+    return this._parent.rotateApiKey(options);
+  }
+
+  async revoke(options: ApiKeysRevokeOptions): Promise<ApiKeyResponse> {
+    return this._parent.revokeApiKey(options);
+  }
+}

src/api/resources/apiKeys/client/Client.ts

@@ -1,4 +1,7 @@
+export { AccountClient } from "./account/client/Client";
+export { ApiKeysClient } from "./apiKeys/client/Client";
 export { AudioIsolationClient } from "./audioIsolation/client/Client";
 export { GenerationsClient } from "./generations/client/Client";
 export { ProjectsClient } from "./projects/client/Client";
+export { UsageClient } from "./usage/client/Client";
 export { WebhooksClient } from "./webhooks/client/Client";