@acedatacloud/sdk 0.0.1

package/src/client.ts

@@ -0,0 +1,56 @@
+/** Top-level AceDataCloud client for TypeScript. */
+
+import { Transport, TransportOptions } from './runtime/transport';
+import { Chat } from './resources/chat';
+import { Images } from './resources/images';
+import { Audio } from './resources/audio';
+import { Video } from './resources/video';
+import { Search } from './resources/search';
+import { Tasks } from './resources/tasks';
+import { Files } from './resources/files';
+import { Platform } from './resources/platform';
+import { OpenAI } from './resources/openai';
+
+export interface AceDataCloudOptions {
+  apiToken?: string;
+  baseURL?: string;
+  platformBaseURL?: string;
+  timeout?: number;
+  maxRetries?: number;
+  headers?: Record<string, string>;
+}
+
+export class AceDataCloud {
+  readonly chat: Chat;
+  readonly images: Images;
+  readonly audio: Audio;
+  readonly video: Video;
+  readonly search: Search;
+  readonly tasks: Tasks;
+  readonly files: Files;
+  readonly platform: Platform;
+  readonly openai: OpenAI;
+
+  private transport: Transport;
+
+  constructor(opts: AceDataCloudOptions = {}) {
+    this.transport = new Transport({
+      apiToken: opts.apiToken,
+      baseURL: opts.baseURL,
+      platformBaseURL: opts.platformBaseURL,
+      timeout: opts.timeout,
+      maxRetries: opts.maxRetries,
+      headers: opts.headers,
+    });
+
+    this.chat = new Chat(this.transport);
+    this.images = new Images(this.transport);
+    this.audio = new Audio(this.transport);
+    this.video = new Video(this.transport);
+    this.search = new Search(this.transport);
+    this.tasks = new Tasks(this.transport);
+    this.files = new Files(this.transport);
+    this.platform = new Platform(this.transport);
+    this.openai = new OpenAI(this.transport);
+  }
+}

package/src/index.ts

@@ -0,0 +1,19 @@
+/** @acedatacloud/sdk — Official TypeScript SDK for AceDataCloud. */
+
+export { AceDataCloud, AceDataCloudOptions } from './client';
+
+export {
+  AceDataCloudError,
+  APIError,
+  AuthenticationError,
+  InsufficientBalanceError,
+  ModerationError,
+  RateLimitError,
+  ResourceDisabledError,
+  TimeoutError,
+  TokenMismatchError,
+  TransportError,
+  ValidationError,
+} from './runtime/errors';
+
+export { TaskHandle, TaskHandleOptions } from './runtime/tasks';

package/src/resources/audio.ts

@@ -0,0 +1,34 @@
+/** Audio/music generation resources. */
+
+import { Transport } from '../runtime/transport';
+import { TaskHandle } from '../runtime/tasks';
+
+export class Audio {
+  constructor(private transport: Transport) {}
+
+  async generate(opts: {
+    prompt: string;
+    model?: string;
+    tags?: string;
+    callbackUrl?: string;
+    wait?: boolean;
+    pollInterval?: number;
+    maxWait?: number;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown> | TaskHandle> {
+    const { prompt, model, tags, callbackUrl, wait: shouldWait, pollInterval, maxWait, ...rest } = opts;
+    const body: Record<string, unknown> = { prompt, ...rest };
+    if (model !== undefined) body.model = model;
+    if (tags !== undefined) body.tags = tags;
+    if (callbackUrl !== undefined) body.callback_url = callbackUrl;
+
+    const result = await this.transport.request('POST', '/suno/audios', { json: body });
+    const taskId = result.task_id as string | undefined;
+
+    if (!taskId || (result.data && !shouldWait)) return result;
+
+    const handle = new TaskHandle(taskId, '/suno/tasks', this.transport);
+    if (shouldWait) return handle.wait({ pollInterval, maxWait });
+    return handle;
+  }
+}

package/src/resources/chat.ts

@@ -0,0 +1,63 @@
+/** Chat resources — native provider APIs (Claude Messages). */
+
+import { Transport } from '../runtime/transport';
+
+export class Messages {
+  constructor(private transport: Transport) {}
+
+  async create(opts: {
+    model: string;
+    messages: Array<Record<string, unknown>>;
+    maxTokens?: number;
+    stream?: false;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown>>;
+  async create(opts: {
+    model: string;
+    messages: Array<Record<string, unknown>>;
+    maxTokens?: number;
+    stream: true;
+    [key: string]: unknown;
+  }): Promise<AsyncGenerator<Record<string, unknown>>>;
+  async create(opts: {
+    model: string;
+    messages: Array<Record<string, unknown>>;
+    maxTokens?: number;
+    stream?: boolean;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown> | AsyncGenerator<Record<string, unknown>>> {
+    const { model, messages, maxTokens = 4096, stream, ...rest } = opts;
+    const body: Record<string, unknown> = { model, messages, max_tokens: maxTokens, ...rest };
+
+    if (stream) {
+      body.stream = true;
+      return this.stream(body);
+    }
+    return this.transport.request('POST', '/v1/messages', { json: body });
+  }
+
+  private async *stream(body: Record<string, unknown>): AsyncGenerator<Record<string, unknown>> {
+    for await (const chunk of this.transport.requestStream('POST', '/v1/messages', { json: body })) {
+      yield JSON.parse(chunk);
+    }
+  }
+
+  async countTokens(opts: {
+    model: string;
+    messages: Array<Record<string, unknown>>;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown>> {
+    const { model, messages, ...rest } = opts;
+    return this.transport.request('POST', '/v1/messages/count_tokens', {
+      json: { model, messages, ...rest },
+    });
+  }
+}
+
+export class Chat {
+  readonly messages: Messages;
+
+  constructor(transport: Transport) {
+    this.messages = new Messages(transport);
+  }
+}

package/src/resources/files.ts

@@ -0,0 +1,27 @@
+/** File upload resources. */
+
+import { Transport } from '../runtime/transport';
+import * as fs from 'fs';
+import * as path from 'path';
+
+export class Files {
+  constructor(private transport: Transport) {}
+
+  async upload(
+    file: string | Buffer | Uint8Array,
+    opts: { filename?: string } = {}
+  ): Promise<Record<string, unknown>> {
+    let data: Buffer | Uint8Array;
+    let filename: string;
+
+    if (typeof file === 'string') {
+      data = fs.readFileSync(file);
+      filename = opts.filename ?? path.basename(file);
+    } else {
+      data = file;
+      filename = opts.filename ?? 'upload';
+    }
+
+    return this.transport.upload('/api/v1/files/', data, filename);
+  }
+}

package/src/resources/images.ts

@@ -0,0 +1,36 @@
+/** Image generation resources. */
+
+import { Transport } from '../runtime/transport';
+import { TaskHandle } from '../runtime/tasks';
+
+export class Images {
+  constructor(private transport: Transport) {}
+
+  async generate(opts: {
+    prompt: string;
+    model?: string;
+    negativePrompt?: string;
+    imageUrl?: string;
+    callbackUrl?: string;
+    wait?: boolean;
+    pollInterval?: number;
+    maxWait?: number;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown> | TaskHandle> {
+    const { prompt, model, negativePrompt, imageUrl, callbackUrl, wait: shouldWait, pollInterval, maxWait, ...rest } = opts;
+    const body: Record<string, unknown> = { prompt, ...rest };
+    if (model !== undefined) body.model = model;
+    if (negativePrompt !== undefined) body.negative_prompt = negativePrompt;
+    if (imageUrl !== undefined) body.image_url = imageUrl;
+    if (callbackUrl !== undefined) body.callback_url = callbackUrl;
+
+    const result = await this.transport.request('POST', '/nano-banana/images', { json: body });
+    const taskId = result.task_id as string | undefined;
+
+    if (!taskId || (result.data && !shouldWait)) return result;
+
+    const handle = new TaskHandle(taskId, '/nano-banana/tasks', this.transport);
+    if (shouldWait) return handle.wait({ pollInterval, maxWait });
+    return handle;
+  }
+}

package/src/resources/openai.ts

@@ -0,0 +1,96 @@
+/** OpenAI-compatible facade resources. */
+
+import { Transport } from '../runtime/transport';
+
+class Completions {
+  constructor(private transport: Transport) {}
+
+  async create(opts: {
+    model: string;
+    messages: Array<Record<string, unknown>>;
+    stream?: false;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown>>;
+  async create(opts: {
+    model: string;
+    messages: Array<Record<string, unknown>>;
+    stream: true;
+    [key: string]: unknown;
+  }): Promise<AsyncGenerator<Record<string, unknown>>>;
+  async create(opts: {
+    model: string;
+    messages: Array<Record<string, unknown>>;
+    stream?: boolean;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown> | AsyncGenerator<Record<string, unknown>>> {
+    const { model, messages, stream, ...rest } = opts;
+    const body: Record<string, unknown> = { model, messages, ...rest };
+
+    if (stream) {
+      body.stream = true;
+      return this.streamResponse(body);
+    }
+    return this.transport.request('POST', '/v1/chat/completions', { json: body });
+  }
+
+  private async *streamResponse(body: Record<string, unknown>): AsyncGenerator<Record<string, unknown>> {
+    for await (const chunk of this.transport.requestStream('POST', '/v1/chat/completions', { json: body })) {
+      yield JSON.parse(chunk);
+    }
+  }
+}
+
+class ChatNamespace {
+  readonly completions: Completions;
+  constructor(transport: Transport) {
+    this.completions = new Completions(transport);
+  }
+}
+
+class Responses {
+  constructor(private transport: Transport) {}
+
+  async create(opts: {
+    model: string;
+    input: string | Array<Record<string, unknown>>;
+    stream?: false;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown>>;
+  async create(opts: {
+    model: string;
+    input: string | Array<Record<string, unknown>>;
+    stream: true;
+    [key: string]: unknown;
+  }): Promise<AsyncGenerator<Record<string, unknown>>>;
+  async create(opts: {
+    model: string;
+    input: string | Array<Record<string, unknown>>;
+    stream?: boolean;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown> | AsyncGenerator<Record<string, unknown>>> {
+    const { model, input, stream, ...rest } = opts;
+    const body: Record<string, unknown> = { model, input, ...rest };
+
+    if (stream) {
+      body.stream = true;
+      return this.streamResponse(body);
+    }
+    return this.transport.request('POST', '/openai/responses', { json: body });
+  }
+
+  private async *streamResponse(body: Record<string, unknown>): AsyncGenerator<Record<string, unknown>> {
+    for await (const chunk of this.transport.requestStream('POST', '/openai/responses', { json: body })) {
+      yield JSON.parse(chunk);
+    }
+  }
+}
+
+export class OpenAI {
+  readonly chat: ChatNamespace;
+  readonly responses: Responses;
+
+  constructor(transport: Transport) {
+    this.chat = new ChatNamespace(transport);
+    this.responses = new Responses(transport);
+  }
+}

package/src/resources/platform.ts

@@ -0,0 +1,77 @@
+/** Management-plane resources. */
+
+import { Transport } from '../runtime/transport';
+
+class Applications {
+  constructor(private transport: Transport) {}
+
+  async list(params?: Record<string, string>): Promise<Record<string, unknown>> {
+    return this.transport.request('GET', '/api/v1/applications/', { params, platform: true });
+  }
+
+  async create(opts: { serviceId: string; [key: string]: unknown }): Promise<Record<string, unknown>> {
+    const { serviceId, ...rest } = opts;
+    return this.transport.request('POST', '/api/v1/applications/', {
+      json: { service_id: serviceId, ...rest },
+      platform: true,
+    });
+  }
+
+  async get(applicationId: string): Promise<Record<string, unknown>> {
+    return this.transport.request('GET', `/api/v1/applications/${applicationId}/`, { platform: true });
+  }
+}
+
+class Credentials {
+  constructor(private transport: Transport) {}
+
+  async list(params?: Record<string, string>): Promise<Record<string, unknown>> {
+    return this.transport.request('GET', '/api/v1/credentials/', { params, platform: true });
+  }
+
+  async create(opts: { applicationId: string; [key: string]: unknown }): Promise<Record<string, unknown>> {
+    const { applicationId, ...rest } = opts;
+    return this.transport.request('POST', '/api/v1/credentials/', {
+      json: { application_id: applicationId, ...rest },
+      platform: true,
+    });
+  }
+
+  async rotate(credentialId: string): Promise<Record<string, unknown>> {
+    return this.transport.request('POST', `/api/v1/credentials/${credentialId}/rotate/`, { platform: true });
+  }
+
+  async delete(credentialId: string): Promise<Record<string, unknown>> {
+    return this.transport.request('DELETE', `/api/v1/credentials/${credentialId}/`, { platform: true });
+  }
+}
+
+class Models {
+  constructor(private transport: Transport) {}
+
+  async list(params?: Record<string, string>): Promise<Record<string, unknown>> {
+    return this.transport.request('GET', '/api/v1/models/', { params, platform: true });
+  }
+}
+
+class Config {
+  constructor(private transport: Transport) {}
+
+  async get(): Promise<Record<string, unknown>> {
+    return this.transport.request('GET', '/api/v1/config/', { platform: true });
+  }
+}
+
+export class Platform {
+  readonly applications: Applications;
+  readonly credentials: Credentials;
+  readonly models: Models;
+  readonly config: Config;
+
+  constructor(transport: Transport) {
+    this.applications = new Applications(transport);
+    this.credentials = new Credentials(transport);
+    this.models = new Models(transport);
+    this.config = new Config(transport);
+  }
+}

package/src/resources/search.ts

@@ -0,0 +1,23 @@
+/** Search resources. */
+
+import { Transport } from '../runtime/transport';
+
+export class Search {
+  constructor(private transport: Transport) {}
+
+  async google(opts: {
+    query: string;
+    type?: string;
+    country?: string;
+    language?: string;
+    page?: number;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown>> {
+    const { query, type = 'search', country, language, page, ...rest } = opts;
+    const body: Record<string, unknown> = { query, type, ...rest };
+    if (country !== undefined) body.country = country;
+    if (language !== undefined) body.language = language;
+    if (page !== undefined) body.page = page;
+    return this.transport.request('POST', '/serp/google', { json: body });
+  }
+}

package/src/resources/tasks.ts

@@ -0,0 +1,38 @@
+/** Cross-service task retrieval. */
+
+import { Transport } from '../runtime/transport';
+import { TaskHandle } from '../runtime/tasks';
+
+const SERVICE_TASK_ENDPOINTS: Record<string, string> = {
+  suno: '/suno/tasks',
+  'nano-banana': '/nano-banana/tasks',
+  seedream: '/seedream/tasks',
+  seedance: '/seedance/tasks',
+  sora: '/sora/tasks',
+  midjourney: '/midjourney/tasks',
+  luma: '/luma/tasks',
+  veo: '/veo/tasks',
+  flux: '/flux/tasks',
+};
+
+export class Tasks {
+  constructor(private transport: Transport) {}
+
+  async get(taskId: string, opts: { service?: string } = {}): Promise<Record<string, unknown>> {
+    const service = opts.service ?? 'suno';
+    const endpoint = SERVICE_TASK_ENDPOINTS[service] ?? `/${service}/tasks`;
+    return this.transport.request('POST', endpoint, {
+      json: { id: taskId, action: 'retrieve' },
+    });
+  }
+
+  async wait(
+    taskId: string,
+    opts: { service?: string; pollInterval?: number; maxWait?: number } = {}
+  ): Promise<Record<string, unknown>> {
+    const service = opts.service ?? 'suno';
+    const endpoint = SERVICE_TASK_ENDPOINTS[service] ?? `/${service}/tasks`;
+    const handle = new TaskHandle(taskId, endpoint, this.transport);
+    return handle.wait({ pollInterval: opts.pollInterval, maxWait: opts.maxWait });
+  }
+}

package/src/resources/video.ts

@@ -0,0 +1,34 @@
+/** Video generation resources. */
+
+import { Transport } from '../runtime/transport';
+import { TaskHandle } from '../runtime/tasks';
+
+export class Video {
+  constructor(private transport: Transport) {}
+
+  async generate(opts: {
+    prompt: string;
+    model?: string;
+    imageUrl?: string;
+    callbackUrl?: string;
+    wait?: boolean;
+    pollInterval?: number;
+    maxWait?: number;
+    [key: string]: unknown;
+  }): Promise<Record<string, unknown> | TaskHandle> {
+    const { prompt, model, imageUrl, callbackUrl, wait: shouldWait, pollInterval, maxWait, ...rest } = opts;
+    const body: Record<string, unknown> = { prompt, ...rest };
+    if (model !== undefined) body.model = model;
+    if (imageUrl !== undefined) body.image_url = imageUrl;
+    if (callbackUrl !== undefined) body.callback_url = callbackUrl;
+
+    const result = await this.transport.request('POST', '/sora/videos', { json: body });
+    const taskId = result.task_id as string | undefined;
+
+    if (!taskId || (result.data && !shouldWait)) return result;
+
+    const handle = new TaskHandle(taskId, '/sora/tasks', this.transport);
+    if (shouldWait) return handle.wait({ pollInterval, maxWait });
+    return handle;
+  }
+}

package/src/runtime/errors.ts

@@ -0,0 +1,93 @@
+/** AceDataCloud SDK errors. */
+
+export class AceDataCloudError extends Error {
+  constructor(message: string) {
+    super(message);
+    this.name = 'AceDataCloudError';
+  }
+}
+
+export class TransportError extends AceDataCloudError {
+  constructor(message: string) {
+    super(message);
+    this.name = 'TransportError';
+  }
+}
+
+export class APIError extends AceDataCloudError {
+  statusCode: number;
+  code: string;
+  traceId?: string;
+  body: Record<string, unknown>;
+
+  constructor(opts: {
+    message: string;
+    statusCode: number;
+    code: string;
+    traceId?: string;
+    body?: Record<string, unknown>;
+  }) {
+    super(opts.message);
+    this.name = 'APIError';
+    this.statusCode = opts.statusCode;
+    this.code = opts.code;
+    this.traceId = opts.traceId;
+    this.body = opts.body ?? {};
+  }
+}
+
+export class AuthenticationError extends APIError {
+  constructor(opts: ConstructorParameters<typeof APIError>[0]) {
+    super(opts);
+    this.name = 'AuthenticationError';
+  }
+}
+
+export class TokenMismatchError extends APIError {
+  constructor(opts: ConstructorParameters<typeof APIError>[0]) {
+    super(opts);
+    this.name = 'TokenMismatchError';
+  }
+}
+
+export class RateLimitError extends APIError {
+  constructor(opts: ConstructorParameters<typeof APIError>[0]) {
+    super(opts);
+    this.name = 'RateLimitError';
+  }
+}
+
+export class ValidationError extends APIError {
+  constructor(opts: ConstructorParameters<typeof APIError>[0]) {
+    super(opts);
+    this.name = 'ValidationError';
+  }
+}
+
+export class InsufficientBalanceError extends APIError {
+  constructor(opts: ConstructorParameters<typeof APIError>[0]) {
+    super(opts);
+    this.name = 'InsufficientBalanceError';
+  }
+}
+
+export class ResourceDisabledError extends APIError {
+  constructor(opts: ConstructorParameters<typeof APIError>[0]) {
+    super(opts);
+    this.name = 'ResourceDisabledError';
+  }
+}
+
+export class ModerationError extends APIError {
+  constructor(opts: ConstructorParameters<typeof APIError>[0]) {
+    super(opts);
+    this.name = 'ModerationError';
+  }
+}
+
+export class TimeoutError extends APIError {
+  constructor(opts: ConstructorParameters<typeof APIError>[0]) {
+    super(opts);
+    this.name = 'TimeoutError';
+  }
+}

package/src/runtime/index.ts

@@ -0,0 +1,15 @@
+export { Transport, TransportOptions } from './transport';
+export { TaskHandle, TaskHandleOptions } from './tasks';
+export {
+  AceDataCloudError,
+  APIError,
+  AuthenticationError,
+  InsufficientBalanceError,
+  ModerationError,
+  RateLimitError,
+  ResourceDisabledError,
+  TimeoutError,
+  TokenMismatchError,
+  TransportError,
+  ValidationError,
+} from './errors';

package/src/runtime/tasks.ts

@@ -0,0 +1,57 @@
+/** Task polling abstraction. */
+
+import { Transport } from './transport';
+
+export interface TaskHandleOptions {
+  pollInterval?: number;
+  maxWait?: number;
+}
+
+export class TaskHandle {
+  readonly id: string;
+  private pollEndpoint: string;
+  private transport: Transport;
+  private _result: Record<string, unknown> | null = null;
+
+  constructor(taskId: string, pollEndpoint: string, transport: Transport) {
+    this.id = taskId;
+    this.pollEndpoint = pollEndpoint;
+    this.transport = transport;
+  }
+
+  async get(): Promise<Record<string, unknown>> {
+    return this.transport.request('POST', this.pollEndpoint, {
+      json: { id: this.id, action: 'retrieve' },
+    });
+  }
+
+  async isCompleted(): Promise<boolean> {
+    const state = await this.get();
+    const response = (state.response ?? state) as Record<string, unknown>;
+    const status = response.status as string;
+    return status === 'succeeded' || status === 'failed';
+  }
+
+  async wait(opts: TaskHandleOptions = {}): Promise<Record<string, unknown>> {
+    const pollInterval = opts.pollInterval ?? 3000;
+    const maxWait = opts.maxWait ?? 600_000;
+    const start = Date.now();
+
+    while (Date.now() - start < maxWait) {
+      const state = await this.get();
+      const response = (state.response ?? state) as Record<string, unknown>;
+      const status = response.status as string;
+
+      if (status === 'succeeded' || status === 'failed') {
+        this._result = state;
+        return state;
+      }
+      await new Promise((resolve) => setTimeout(resolve, pollInterval));
+    }
+    throw new Error(`Task ${this.id} did not complete within ${maxWait}ms`);
+  }
+
+  get result(): Record<string, unknown> | null {
+    return this._result;
+  }
+}