@defoai/ads-client 1.4.0

package/dist/generated/runtime.d.ts

@@ -0,0 +1,182 @@
+/**
+ * Defo Ads Public API
+ * Stable public API for managing campaigns, ads, keywords, and sites.
+ *
+ * The version of the OpenAPI document: 1.4.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+export declare const BASE_PATH: string;
+export interface ConfigurationParameters {
+    basePath?: string;
+    fetchApi?: FetchAPI;
+    middleware?: Middleware[];
+    queryParamsStringify?: (params: HTTPQuery) => string;
+    username?: string;
+    password?: string;
+    apiKey?: string | Promise<string> | ((name: string) => string | Promise<string>);
+    accessToken?: string | Promise<string> | ((name?: string, scopes?: string[]) => string | Promise<string>);
+    headers?: HTTPHeaders;
+    credentials?: RequestCredentials;
+}
+export declare class Configuration {
+    private configuration;
+    constructor(configuration?: ConfigurationParameters);
+    set config(configuration: Configuration);
+    get basePath(): string;
+    get fetchApi(): FetchAPI | undefined;
+    get middleware(): Middleware[];
+    get queryParamsStringify(): (params: HTTPQuery) => string;
+    get username(): string | undefined;
+    get password(): string | undefined;
+    get apiKey(): ((name: string) => string | Promise<string>) | undefined;
+    get accessToken(): ((name?: string, scopes?: string[]) => string | Promise<string>) | undefined;
+    get headers(): HTTPHeaders | undefined;
+    get credentials(): RequestCredentials | undefined;
+}
+export declare const DefaultConfig: Configuration;
+/**
+ * This is the base class for all generated API classes.
+ */
+export declare class BaseAPI {
+    protected configuration: Configuration;
+    private static readonly jsonRegex;
+    private middleware;
+    constructor(configuration?: Configuration);
+    withMiddleware<T extends BaseAPI>(this: T, ...middlewares: Middleware[]): T;
+    withPreMiddleware<T extends BaseAPI>(this: T, ...preMiddlewares: Array<Middleware['pre']>): T;
+    withPostMiddleware<T extends BaseAPI>(this: T, ...postMiddlewares: Array<Middleware['post']>): T;
+    /**
+     * Check if the given MIME is a JSON MIME.
+     * JSON MIME examples:
+     *   application/json
+     *   application/json; charset=UTF8
+     *   APPLICATION/JSON
+     *   application/vnd.company+json
+     * @param mime - MIME (Multipurpose Internet Mail Extensions)
+     * @return True if the given MIME is JSON, false otherwise.
+     */
+    protected isJsonMime(mime: string | null | undefined): boolean;
+    protected request(context: RequestOpts, initOverrides?: RequestInit | InitOverrideFunction): Promise<Response>;
+    private createFetchParams;
+    private fetchApi;
+    /**
+     * Create a shallow clone of `this` by constructing a new instance
+     * and then shallow cloning data members.
+     */
+    private clone;
+}
+export declare class ResponseError extends Error {
+    response: Response;
+    name: "ResponseError";
+    constructor(response: Response, msg?: string);
+}
+export declare class FetchError extends Error {
+    cause: Error;
+    name: "FetchError";
+    constructor(cause: Error, msg?: string);
+}
+export declare class RequiredError extends Error {
+    field: string;
+    name: "RequiredError";
+    constructor(field: string, msg?: string);
+}
+export declare const COLLECTION_FORMATS: {
+    csv: string;
+    ssv: string;
+    tsv: string;
+    pipes: string;
+};
+export type FetchAPI = WindowOrWorkerGlobalScope['fetch'];
+export type Json = any;
+export type HTTPMethod = 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS' | 'HEAD';
+export type HTTPHeaders = {
+    [key: string]: string;
+};
+export type HTTPQuery = {
+    [key: string]: string | number | null | boolean | Array<string | number | null | boolean> | Set<string | number | null | boolean> | HTTPQuery;
+};
+export type HTTPBody = Json | FormData | URLSearchParams;
+export type HTTPRequestInit = {
+    headers?: HTTPHeaders;
+    method: HTTPMethod;
+    credentials?: RequestCredentials;
+    body?: HTTPBody;
+};
+export type ModelPropertyNaming = 'camelCase' | 'snake_case' | 'PascalCase' | 'original';
+export type InitOverrideFunction = (requestContext: {
+    init: HTTPRequestInit;
+    context: RequestOpts;
+}) => Promise<RequestInit>;
+export interface FetchParams {
+    url: string;
+    init: RequestInit;
+}
+export interface RequestOpts {
+    path: string;
+    method: HTTPMethod;
+    headers: HTTPHeaders;
+    query?: HTTPQuery;
+    body?: HTTPBody;
+}
+export declare function querystring(params: HTTPQuery, prefix?: string): string;
+export declare function exists(json: any, key: string): boolean;
+export declare function mapValues(data: any, fn: (item: any) => any): {};
+export declare function canConsumeForm(consumes: Consume[]): boolean;
+export interface Consume {
+    contentType: string;
+}
+export interface RequestContext {
+    fetch: FetchAPI;
+    url: string;
+    init: RequestInit;
+}
+export interface ResponseContext {
+    fetch: FetchAPI;
+    url: string;
+    init: RequestInit;
+    response: Response;
+}
+export interface ErrorContext {
+    fetch: FetchAPI;
+    url: string;
+    init: RequestInit;
+    error: unknown;
+    response?: Response;
+}
+export interface Middleware {
+    pre?(context: RequestContext): Promise<FetchParams | void>;
+    post?(context: ResponseContext): Promise<Response | void>;
+    onError?(context: ErrorContext): Promise<Response | void>;
+}
+export interface ApiResponse<T> {
+    raw: Response;
+    value(): Promise<T>;
+}
+export interface ResponseTransformer<T> {
+    (json: any): T;
+}
+export declare class JSONApiResponse<T> {
+    raw: Response;
+    private transformer;
+    constructor(raw: Response, transformer?: ResponseTransformer<T>);
+    value(): Promise<T>;
+}
+export declare class VoidApiResponse {
+    raw: Response;
+    constructor(raw: Response);
+    value(): Promise<void>;
+}
+export declare class BlobApiResponse {
+    raw: Response;
+    constructor(raw: Response);
+    value(): Promise<Blob>;
+}
+export declare class TextApiResponse {
+    raw: Response;
+    constructor(raw: Response);
+    value(): Promise<string>;
+}

package/dist/generated/runtime.js

@@ -0,0 +1,318 @@
+/* tslint:disable */
+/* eslint-disable */
+/**
+ * Defo Ads Public API
+ * Stable public API for managing campaigns, ads, keywords, and sites.
+ *
+ * The version of the OpenAPI document: 1.4.0
+ *
+ *
+ * NOTE: This class is auto generated by OpenAPI Generator (https://openapi-generator.tech).
+ * https://openapi-generator.tech
+ * Do not edit the class manually.
+ */
+export const BASE_PATH = "https://api.ads.defoai.com".replace(/\/+$/, "");
+export class Configuration {
+    constructor(configuration = {}) {
+        this.configuration = configuration;
+    }
+    set config(configuration) {
+        this.configuration = configuration;
+    }
+    get basePath() {
+        return this.configuration.basePath != null ? this.configuration.basePath : BASE_PATH;
+    }
+    get fetchApi() {
+        return this.configuration.fetchApi;
+    }
+    get middleware() {
+        return this.configuration.middleware || [];
+    }
+    get queryParamsStringify() {
+        return this.configuration.queryParamsStringify || querystring;
+    }
+    get username() {
+        return this.configuration.username;
+    }
+    get password() {
+        return this.configuration.password;
+    }
+    get apiKey() {
+        const apiKey = this.configuration.apiKey;
+        if (apiKey) {
+            return typeof apiKey === 'function' ? apiKey : () => apiKey;
+        }
+        return undefined;
+    }
+    get accessToken() {
+        const accessToken = this.configuration.accessToken;
+        if (accessToken) {
+            return typeof accessToken === 'function' ? accessToken : async () => accessToken;
+        }
+        return undefined;
+    }
+    get headers() {
+        return this.configuration.headers;
+    }
+    get credentials() {
+        return this.configuration.credentials;
+    }
+}
+export const DefaultConfig = new Configuration();
+/**
+ * This is the base class for all generated API classes.
+ */
+export class BaseAPI {
+    constructor(configuration = DefaultConfig) {
+        this.configuration = configuration;
+        this.fetchApi = async (url, init) => {
+            let fetchParams = { url, init };
+            for (const middleware of this.middleware) {
+                if (middleware.pre) {
+                    fetchParams = await middleware.pre({
+                        fetch: this.fetchApi,
+                        ...fetchParams,
+                    }) || fetchParams;
+                }
+            }
+            let response = undefined;
+            try {
+                response = await (this.configuration.fetchApi || fetch)(fetchParams.url, fetchParams.init);
+            }
+            catch (e) {
+                for (const middleware of this.middleware) {
+                    if (middleware.onError) {
+                        response = await middleware.onError({
+                            fetch: this.fetchApi,
+                            url: fetchParams.url,
+                            init: fetchParams.init,
+                            error: e,
+                            response: response ? response.clone() : undefined,
+                        }) || response;
+                    }
+                }
+                if (response === undefined) {
+                    if (e instanceof Error) {
+                        throw new FetchError(e, 'The request failed and the interceptors did not return an alternative response');
+                    }
+                    else {
+                        throw e;
+                    }
+                }
+            }
+            for (const middleware of this.middleware) {
+                if (middleware.post) {
+                    response = await middleware.post({
+                        fetch: this.fetchApi,
+                        url: fetchParams.url,
+                        init: fetchParams.init,
+                        response: response.clone(),
+                    }) || response;
+                }
+            }
+            return response;
+        };
+        this.middleware = configuration.middleware;
+    }
+    withMiddleware(...middlewares) {
+        const next = this.clone();
+        next.middleware = next.middleware.concat(...middlewares);
+        return next;
+    }
+    withPreMiddleware(...preMiddlewares) {
+        const middlewares = preMiddlewares.map((pre) => ({ pre }));
+        return this.withMiddleware(...middlewares);
+    }
+    withPostMiddleware(...postMiddlewares) {
+        const middlewares = postMiddlewares.map((post) => ({ post }));
+        return this.withMiddleware(...middlewares);
+    }
+    /**
+     * Check if the given MIME is a JSON MIME.
+     * JSON MIME examples:
+     *   application/json
+     *   application/json; charset=UTF8
+     *   APPLICATION/JSON
+     *   application/vnd.company+json
+     * @param mime - MIME (Multipurpose Internet Mail Extensions)
+     * @return True if the given MIME is JSON, false otherwise.
+     */
+    isJsonMime(mime) {
+        if (!mime) {
+            return false;
+        }
+        return BaseAPI.jsonRegex.test(mime);
+    }
+    async request(context, initOverrides) {
+        const { url, init } = await this.createFetchParams(context, initOverrides);
+        const response = await this.fetchApi(url, init);
+        if (response && (response.status >= 200 && response.status < 300)) {
+            return response;
+        }
+        throw new ResponseError(response, 'Response returned an error code');
+    }
+    async createFetchParams(context, initOverrides) {
+        let url = this.configuration.basePath + context.path;
+        if (context.query !== undefined && Object.keys(context.query).length !== 0) {
+            // only add the querystring to the URL if there are query parameters.
+            // this is done to avoid urls ending with a "?" character which buggy webservers
+            // do not handle correctly sometimes.
+            url += '?' + this.configuration.queryParamsStringify(context.query);
+        }
+        const headers = Object.assign({}, this.configuration.headers, context.headers);
+        Object.keys(headers).forEach(key => headers[key] === undefined ? delete headers[key] : {});
+        const initOverrideFn = typeof initOverrides === "function"
+            ? initOverrides
+            : async () => initOverrides;
+        const initParams = {
+            method: context.method,
+            headers,
+            body: context.body,
+            credentials: this.configuration.credentials,
+        };
+        const overriddenInit = {
+            ...initParams,
+            ...(await initOverrideFn({
+                init: initParams,
+                context,
+            }))
+        };
+        let body;
+        if (isFormData(overriddenInit.body)
+            || (overriddenInit.body instanceof URLSearchParams)
+            || isBlob(overriddenInit.body)) {
+            body = overriddenInit.body;
+        }
+        else if (this.isJsonMime(headers['Content-Type'])) {
+            body = JSON.stringify(overriddenInit.body);
+        }
+        else {
+            body = overriddenInit.body;
+        }
+        const init = {
+            ...overriddenInit,
+            body
+        };
+        return { url, init };
+    }
+    /**
+     * Create a shallow clone of `this` by constructing a new instance
+     * and then shallow cloning data members.
+     */
+    clone() {
+        const constructor = this.constructor;
+        const next = new constructor(this.configuration);
+        next.middleware = this.middleware.slice();
+        return next;
+    }
+}
+BaseAPI.jsonRegex = new RegExp('^(:?application\/json|[^;/ \t]+\/[^;/ \t]+[+]json)[ \t]*(:?;.*)?$', 'i');
+;
+function isBlob(value) {
+    return typeof Blob !== 'undefined' && value instanceof Blob;
+}
+function isFormData(value) {
+    return typeof FormData !== "undefined" && value instanceof FormData;
+}
+export class ResponseError extends Error {
+    constructor(response, msg) {
+        super(msg);
+        this.response = response;
+        this.name = "ResponseError";
+    }
+}
+export class FetchError extends Error {
+    constructor(cause, msg) {
+        super(msg);
+        this.cause = cause;
+        this.name = "FetchError";
+    }
+}
+export class RequiredError extends Error {
+    constructor(field, msg) {
+        super(msg);
+        this.field = field;
+        this.name = "RequiredError";
+    }
+}
+export const COLLECTION_FORMATS = {
+    csv: ",",
+    ssv: " ",
+    tsv: "\t",
+    pipes: "|",
+};
+export function querystring(params, prefix = '') {
+    return Object.keys(params)
+        .map(key => querystringSingleKey(key, params[key], prefix))
+        .filter(part => part.length > 0)
+        .join('&');
+}
+function querystringSingleKey(key, value, keyPrefix = '') {
+    const fullKey = keyPrefix + (keyPrefix.length ? `[${key}]` : key);
+    if (value instanceof Array) {
+        const multiValue = value.map(singleValue => encodeURIComponent(String(singleValue)))
+            .join(`&${encodeURIComponent(fullKey)}=`);
+        return `${encodeURIComponent(fullKey)}=${multiValue}`;
+    }
+    if (value instanceof Set) {
+        const valueAsArray = Array.from(value);
+        return querystringSingleKey(key, valueAsArray, keyPrefix);
+    }
+    if (value instanceof Date) {
+        return `${encodeURIComponent(fullKey)}=${encodeURIComponent(value.toISOString())}`;
+    }
+    if (value instanceof Object) {
+        return querystring(value, fullKey);
+    }
+    return `${encodeURIComponent(fullKey)}=${encodeURIComponent(String(value))}`;
+}
+export function exists(json, key) {
+    const value = json[key];
+    return value !== null && value !== undefined;
+}
+export function mapValues(data, fn) {
+    return Object.keys(data).reduce((acc, key) => ({ ...acc, [key]: fn(data[key]) }), {});
+}
+export function canConsumeForm(consumes) {
+    for (const consume of consumes) {
+        if ('multipart/form-data' === consume.contentType) {
+            return true;
+        }
+    }
+    return false;
+}
+export class JSONApiResponse {
+    constructor(raw, transformer = (jsonValue) => jsonValue) {
+        this.raw = raw;
+        this.transformer = transformer;
+    }
+    async value() {
+        return this.transformer(await this.raw.json());
+    }
+}
+export class VoidApiResponse {
+    constructor(raw) {
+        this.raw = raw;
+    }
+    async value() {
+        return undefined;
+    }
+}
+export class BlobApiResponse {
+    constructor(raw) {
+        this.raw = raw;
+    }
+    async value() {
+        return await this.raw.blob();
+    }
+    ;
+}
+export class TextApiResponse {
+    constructor(raw) {
+        this.raw = raw;
+    }
+    async value() {
+        return await this.raw.text();
+    }
+    ;
+}

package/dist/index.d.ts

@@ -0,0 +1,177 @@
+import { type CampaignCreate, type CampaignUpdate, type AdGroupCreate, type AdGroupUpdate, type AdCreate, type AdUpdate, type KeywordCreate, type KeywordUpdate, type SiteCreate, type SiteUpdate, type AssetCreate, type AssetUpdate, type CampaignAssetCreate, type AdAssetCreate, type SyncTriggerRequest, type SyncUnlinkRequest } from './generated';
+/** The production base URL. Override via `baseUrl` (e.g. for staging). */
+export declare const PRODUCTION_BASE_URL = "https://api.ads.defoai.com";
+export declare const STAGING_BASE_URL = "https://api-ads-staging.defoai.com";
+export interface DefoAdsOptions {
+    /** A Defo Ads personal access token (`dads_…`). Required. */
+    token: string;
+    /** Default Space id (`spc_…`) sent as `X-Space-Id` on every call. Omit to use your Personal Space. */
+    space?: string;
+    /** Base URL. Defaults to production. Use {@link STAGING_BASE_URL} for staging. */
+    baseUrl?: string;
+    /** Max automatic retries on 429 / 5xx. Default 3. */
+    maxRetries?: number;
+    /** Inject a fetch implementation (handy for tests / non-global-fetch runtimes). */
+    fetch?: typeof fetch;
+}
+/** Base error for any non-2xx response; carries the API's `{ code, message, details }`. */
+export declare class DefoAdsError extends Error {
+    readonly status: number;
+    readonly code?: string;
+    readonly details?: unknown;
+    constructor(status: number, code: string | undefined, message: string, details?: unknown);
+}
+/** 401 — missing/invalid token. */ export declare class AuthError extends DefoAdsError {
+    name: string;
+}
+/** 403 — token lacks the required scope or Space membership. */ export declare class ForbiddenError extends DefoAdsError {
+    name: string;
+}
+/** 404 — resource not found (or outside your Space). */ export declare class NotFoundError extends DefoAdsError {
+    name: string;
+}
+/** 409 — conflict (e.g. delete blocked by dependents, or a sync already running). */ export declare class ConflictError extends DefoAdsError {
+    name: string;
+}
+/** 429 — rate limited. The SDK already retried up to `maxRetries`. */ export declare class RateLimitError extends DefoAdsError {
+    name: string;
+}
+interface ListParams {
+    limit?: number;
+    cursor?: string | number;
+}
+/** The Defo Ads client. Construct once, reuse everywhere. */
+export declare class DefoAds {
+    readonly campaigns: {
+        /** List one page (default 50, max 200). */
+        list: (params?: ListParams) => Promise<any[]>;
+        /** Async-iterate EVERY item across all pages (follows `meta.nextCursor`). */
+        listAll(params?: ListParams): AsyncGenerator<any>;
+        /** Fetch one by id. */
+        get: (id: string) => Promise<any>;
+        /** Create. */
+        create: (body: CampaignCreate) => Promise<any>;
+        /** Partial update by id. */
+        update: (id: string, body: CampaignUpdate) => Promise<any>;
+        /** Delete by id. */
+        delete: (id: string) => Promise<any>;
+    };
+    readonly adGroups: {
+        /** List one page (default 50, max 200). */
+        list: (params?: ListParams) => Promise<any[]>;
+        /** Async-iterate EVERY item across all pages (follows `meta.nextCursor`). */
+        listAll(params?: ListParams): AsyncGenerator<any>;
+        /** Fetch one by id. */
+        get: (id: string) => Promise<any>;
+        /** Create. */
+        create: (body: AdGroupCreate) => Promise<any>;
+        /** Partial update by id. */
+        update: (id: string, body: AdGroupUpdate) => Promise<any>;
+        /** Delete by id. */
+        delete: (id: string) => Promise<any>;
+    };
+    readonly ads: {
+        /** List one page (default 50, max 200). */
+        list: (params?: ListParams) => Promise<any[]>;
+        /** Async-iterate EVERY item across all pages (follows `meta.nextCursor`). */
+        listAll(params?: ListParams): AsyncGenerator<any>;
+        /** Fetch one by id. */
+        get: (id: string) => Promise<any>;
+        /** Create. */
+        create: (body: AdCreate) => Promise<any>;
+        /** Partial update by id. */
+        update: (id: string, body: AdUpdate) => Promise<any>;
+        /** Delete by id. */
+        delete: (id: string) => Promise<any>;
+    };
+    readonly keywords: {
+        /** List one page (default 50, max 200). */
+        list: (params?: ListParams) => Promise<any[]>;
+        /** Async-iterate EVERY item across all pages (follows `meta.nextCursor`). */
+        listAll(params?: ListParams): AsyncGenerator<any>;
+        /** Fetch one by id. */
+        get: (id: string) => Promise<any>;
+        /** Create. */
+        create: (body: KeywordCreate) => Promise<any>;
+        /** Partial update by id. */
+        update: (id: string, body: KeywordUpdate) => Promise<any>;
+        /** Delete by id. */
+        delete: (id: string) => Promise<any>;
+    };
+    readonly sites: {
+        /** List one page (default 50, max 200). */
+        list: (params?: ListParams) => Promise<any[]>;
+        /** Async-iterate EVERY item across all pages (follows `meta.nextCursor`). */
+        listAll(params?: ListParams): AsyncGenerator<any>;
+        /** Fetch one by id. */
+        get: (id: string) => Promise<any>;
+        /** Create. */
+        create: (body: SiteCreate) => Promise<any>;
+        /** Partial update by id. */
+        update: (id: string, body: SiteUpdate) => Promise<any>;
+        /** Delete by id. */
+        delete: (id: string) => Promise<any>;
+    };
+    readonly assets: {
+        /** List one page (default 50, max 200). */
+        list: (params?: ListParams) => Promise<any[]>;
+        /** Async-iterate EVERY item across all pages (follows `meta.nextCursor`). */
+        listAll(params?: ListParams): AsyncGenerator<any>;
+        /** Fetch one by id. */
+        get: (id: string) => Promise<any>;
+        /** Create. */
+        create: (body: AssetCreate) => Promise<any>;
+        /** Partial update by id. */
+        update: (id: string, body: AssetUpdate) => Promise<any>;
+        /** Delete by id. */
+        delete: (id: string) => Promise<any>;
+    };
+    readonly campaignAssets: {
+        list: (p?: ListParams & {
+            campaignId?: string;
+            assetId?: string;
+        }) => Promise<any>;
+        get: (id: string) => Promise<any>;
+        create: (body: CampaignAssetCreate) => Promise<any>;
+        delete: (id: string) => Promise<any>;
+    };
+    readonly adAssets: {
+        list: (p?: ListParams & {
+            adId?: string;
+            adGroupId?: string;
+            campaignId?: string;
+            role?: string;
+        }) => Promise<any>;
+        get: (id: string) => Promise<any>;
+        create: (body: AdAssetCreate) => Promise<any>;
+        delete: (id: string) => Promise<any>;
+    };
+    readonly media: {
+        matrix: () => Promise<any>;
+    };
+    readonly reports: {
+        /** Performance stats; see the reference for `date_range`, `group_by`, `metrics`, etc. */
+        stats: (params?: Record<string, any>) => Promise<any>;
+    };
+    readonly sync: {
+        /** Trigger a sync for the active Space (async — poll `get(syncId)`). */
+        trigger: (body?: SyncTriggerRequest) => Promise<any>;
+        list: (p?: ListParams) => Promise<any>;
+        /** Dry-run plan (import/export/remove) without executing. */
+        plan: (p?: {
+            platforms?: string;
+        }) => Promise<any>;
+        get: (id: string) => Promise<any>;
+        cancel: (id: string) => Promise<any>;
+        /** Unlink campaigns from a platform (keeps the local campaign). */
+        unlink: (body: SyncUnlinkRequest) => Promise<any>;
+    };
+    readonly meta: {
+        /** Introspect the authenticated token. */
+        me: () => Promise<any>;
+        /** List Spaces the token can access. */
+        spaces: () => Promise<any>;
+    };
+    constructor(options: DefoAdsOptions);
+}
+export default DefoAds;