@hunt-labs/bytekit-sdk 0.2.2 → 0.4.0

package/dist/resources/screenshots.d.ts

@@ -1,4 +1,4 @@
-import type { RapidCrawl } from '../client.js';
+import type { ApiResponse, ByteKit, RequestOptions } from '../client.js';
 import type { operations } from '../generated/api.js';
 import type { ScreenshotId } from '../types.js';
 /** The `createScreenshot` request body exactly as the OpenAPI spec declares it. */
@@ -47,15 +47,52 @@ export type ScreenshotCreateResponse = operations['createScreenshot']['responses
 export type ScreenshotGetResponse = operations['getScreenshot']['responses'][200]['content']['application/json'] | operations['getScreenshot']['responses'][202]['content']['application/json'];
 export declare class ScreenshotsResource {
     private readonly client;
-    constructor(client: RapidCrawl);
-    /** POST /v1/screenshots — capture a screenshot */
-    create(opts: ScreenshotCreateRequest): Promise<ScreenshotCreateResponse>;
+    constructor(client: ByteKit);
+    /**
+     * POST /v1/screenshots — capture a screenshot.
+     *
+     * `params.async` maps to the `?async=true` query param (queued 202 capture). It is a QUERY
+     * param on `createScreenshot`, distinct from scrape where `async` is a body field. `params` is
+     * optional and `async` omitted-when-absent: `create(opts)` with no second argument posts to the
+     * bare `/v1/screenshots` URL unchanged — existing single-arg callers are unaffected.
+     *
+     * `requestOptions` is the THIRD positional parameter (after `params`) so both existing call
+     * shapes stay unaffected. It carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    create(opts: ScreenshotCreateRequest, params?: {
+        async?: boolean;
+    }, requestOptions?: RequestOptions): Promise<ScreenshotCreateResponse>;
     /**
      * GET /v1/screenshots/{id} — poll a screenshot by ID.
      *
      * A terminal-`failed` screenshot returns the `Error` envelope on a 200
      * (issue #2027), so narrow the result before reading `image_url`.
      */
-    get(id: ScreenshotId): Promise<ScreenshotGetResponse>;
+    get(id: ScreenshotId, requestOptions?: RequestOptions): Promise<ScreenshotGetResponse>;
+    /**
+     * POST /v1/screenshots, returning the header set alongside the body (#2547).
+     *
+     * Same request as `screenshots.create` — same method, path, body and
+     * `RequestOptions` precedence — and `data` is exactly what `create()` resolves to.
+     * `create()`'s own return type is UNCHANGED; this is an additive sibling.
+     *
+     * The spec documents the `X-Screenshot-*` family (`ID`, `Status`, `URL`,
+     * `Credits-Charged`, `Duration-Ms`, `Created-At`, `Completed-At`, `Expires-At`,
+     * `Status-Code`, `Cache`, `Cache-Age`) plus `X-Raw-Bytes` / `X-Billable-Bytes` /
+     * `X-Billing-Multiplier`; every one of them is on `headers`.
+     */
+    createWithResponse(opts: ScreenshotCreateRequest, params?: {
+        async?: boolean;
+    }, requestOptions?: RequestOptions): Promise<ApiResponse<ScreenshotCreateResponse>>;
+    /**
+     * GET /v1/screenshots/{id}, returning the header set alongside the body (#2547).
+     *
+     * Same request as `screenshots.get`, and `data` is exactly what `get()`
+     * resolves to (including the #2027 failed-envelope arm). `get()`'s own return type is
+     * UNCHANGED; this is an additive sibling. The documented `X-Screenshot-*`,
+     * `X-Raw-Bytes`, `X-Billable-Bytes` and `X-Billing-Multiplier` headers are on `headers`.
+     */
+    getWithResponse(id: ScreenshotId, requestOptions?: RequestOptions): Promise<ApiResponse<ScreenshotGetResponse>>;
 }
 export {};

package/dist/resources/screenshots.js

@@ -3,9 +3,21 @@ export class ScreenshotsResource {
     constructor(client) {
         this.client = client;
     }
-    /** POST /v1/screenshots — capture a screenshot */
-    create(opts) {
-        return this.client.request('POST', '/v1/screenshots', opts);
+    /**
+     * POST /v1/screenshots — capture a screenshot.
+     *
+     * `params.async` maps to the `?async=true` query param (queued 202 capture). It is a QUERY
+     * param on `createScreenshot`, distinct from scrape where `async` is a body field. `params` is
+     * optional and `async` omitted-when-absent: `create(opts)` with no second argument posts to the
+     * bare `/v1/screenshots` URL unchanged — existing single-arg callers are unaffected.
+     *
+     * `requestOptions` is the THIRD positional parameter (after `params`) so both existing call
+     * shapes stay unaffected. It carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    create(opts, params, requestOptions) {
+        const suffix = params?.async === true ? '?async=true' : '';
+        return this.client.request('POST', `/v1/screenshots${suffix}`, opts, requestOptions);
     }
     /**
      * GET /v1/screenshots/{id} — poll a screenshot by ID.
@@ -13,7 +25,34 @@ export class ScreenshotsResource {
      * A terminal-`failed` screenshot returns the `Error` envelope on a 200
      * (issue #2027), so narrow the result before reading `image_url`.
      */
-    get(id) {
-        return this.client.request('GET', `/v1/screenshots/${id}`);
+    get(id, requestOptions) {
+        return this.client.request('GET', `/v1/screenshots/${id}`, undefined, requestOptions);
+    }
+    /**
+     * POST /v1/screenshots, returning the header set alongside the body (#2547).
+     *
+     * Same request as `screenshots.create` — same method, path, body and
+     * `RequestOptions` precedence — and `data` is exactly what `create()` resolves to.
+     * `create()`'s own return type is UNCHANGED; this is an additive sibling.
+     *
+     * The spec documents the `X-Screenshot-*` family (`ID`, `Status`, `URL`,
+     * `Credits-Charged`, `Duration-Ms`, `Created-At`, `Completed-At`, `Expires-At`,
+     * `Status-Code`, `Cache`, `Cache-Age`) plus `X-Raw-Bytes` / `X-Billable-Bytes` /
+     * `X-Billing-Multiplier`; every one of them is on `headers`.
+     */
+    createWithResponse(opts, params, requestOptions) {
+        const suffix = params?.async === true ? '?async=true' : '';
+        return this.client.requestWithResponse('POST', `/v1/screenshots${suffix}`, opts, requestOptions);
+    }
+    /**
+     * GET /v1/screenshots/{id}, returning the header set alongside the body (#2547).
+     *
+     * Same request as `screenshots.get`, and `data` is exactly what `get()`
+     * resolves to (including the #2027 failed-envelope arm). `get()`'s own return type is
+     * UNCHANGED; this is an additive sibling. The documented `X-Screenshot-*`,
+     * `X-Raw-Bytes`, `X-Billable-Bytes` and `X-Billing-Multiplier` headers are on `headers`.
+     */
+    getWithResponse(id, requestOptions) {
+        return this.client.requestWithResponse('GET', `/v1/screenshots/${id}`, undefined, requestOptions);
     }
 }

package/dist/resources/search.d.ts

@@ -1,8 +1,13 @@
-import type { RapidCrawl } from '../client.js';
+import type { ByteKit, RequestOptions } from '../client.js';
 import type { SearchOpts, SearchResponse } from '../types.js';
 export declare class SearchResource {
     private readonly client;
-    constructor(client: RapidCrawl);
-    /** POST /v1/search — run a web search and return ranked organic results. */
-    query(opts: SearchOpts): Promise<SearchResponse>;
+    constructor(client: ByteKit);
+    /**
+     * POST /v1/search — run a web search and return ranked organic results.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    query(opts: SearchOpts, requestOptions?: RequestOptions): Promise<SearchResponse>;
 }

package/dist/resources/search.js

@@ -3,8 +3,13 @@ export class SearchResource {
     constructor(client) {
         this.client = client;
     }
-    /** POST /v1/search — run a web search and return ranked organic results. */
-    query(opts) {
-        return this.client.request('POST', '/v1/search', opts);
+    /**
+     * POST /v1/search — run a web search and return ranked organic results.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    query(opts, requestOptions) {
+        return this.client.request('POST', '/v1/search', opts, requestOptions);
     }
 }

package/dist/resources/sitemap.d.ts

@@ -1,10 +1,46 @@
-import type { RapidCrawl } from '../client.js';
+import type { ApiResponse, ByteKit, RequestOptions } from '../client.js';
+import type { operations } from '../generated/api.js';
 import type { SitemapId } from '../types.js';
+/** The `createSitemap` request body exactly as the OpenAPI spec declares it. */
+type SitemapRequestSpec = operations['createSitemap']['requestBody']['content']['application/json'];
+/**
+ * Body of POST /v1/sitemap — `url` is required, every other field optional.
+ *
+ * Same `defaultNonNullable` drift documented on `ScreenshotCreateRequest`
+ * (screenshots.ts:12-31, follow-up #2540): the spec says `required: [url]`
+ * (openapi.yaml `SitemapRequest`) but 7 sibling fields carry `default:`, which
+ * `openapi-typescript` v7's `defaultNonNullable` transform promotes to
+ * non-optional in the generated type. Relaxed here so the spec-minimal
+ * `create({ url })` compiles — still DERIVED from the operation type, never
+ * hand-authored.
+ */
+export type SitemapCreateRequest = Partial<SitemapRequestSpec> & Pick<SitemapRequestSpec, 'url'>;
+/** 202 payload of POST /v1/sitemap — sitemap crawls are always async. */
+export type SitemapCreateResponse = operations['createSitemap']['responses'][202]['content']['application/json'];
+/** 200 payload of GET /v1/sitemap/{id}. */
+export type SitemapGetResponse = operations['getSitemap']['responses'][200]['content']['application/json'];
 export declare class SitemapResource {
     private readonly client;
-    constructor(client: RapidCrawl);
-    /** POST /v1/sitemap — start a sitemap crawl */
-    create(opts: Record<string, unknown>): Promise<unknown>;
+    constructor(client: ByteKit);
+    /**
+     * POST /v1/sitemap — start a sitemap crawl.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    create(opts: SitemapCreateRequest, requestOptions?: RequestOptions): Promise<SitemapCreateResponse>;
     /** GET /v1/sitemap/{id} — get a sitemap job by ID */
-    get(id: SitemapId): Promise<unknown>;
+    get(id: SitemapId, requestOptions?: RequestOptions): Promise<SitemapGetResponse>;
+    /**
+     * GET /v1/sitemap/{id}, returning the header set alongside the body (#2547).
+     *
+     * Same request as `sitemap.get` — same method, path and `RequestOptions`
+     * precedence — and `data` is exactly what `get()` resolves to. `get()`'s own return type
+     * is UNCHANGED; this is an additive sibling, not a replacement.
+     *
+     * The spec documents `X-Sitemap-ID`, `X-Raw-Bytes`, `X-Billing-Multiplier` and
+     * `X-Billable-Bytes` on this endpoint's 200; every one of them is on `headers`.
+     */
+    getWithResponse(id: SitemapId, requestOptions?: RequestOptions): Promise<ApiResponse<SitemapGetResponse>>;
 }
+export {};

package/dist/resources/sitemap.js

@@ -3,12 +3,30 @@ export class SitemapResource {
     constructor(client) {
         this.client = client;
     }
-    /** POST /v1/sitemap — start a sitemap crawl */
-    create(opts) {
-        return this.client.request('POST', '/v1/sitemap', opts);
+    /**
+     * POST /v1/sitemap — start a sitemap crawl.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    create(opts, requestOptions) {
+        return this.client.request('POST', '/v1/sitemap', opts, requestOptions);
     }
     /** GET /v1/sitemap/{id} — get a sitemap job by ID */
-    get(id) {
-        return this.client.request('GET', `/v1/sitemap/${id}`);
+    get(id, requestOptions) {
+        return this.client.request('GET', `/v1/sitemap/${id}`, undefined, requestOptions);
+    }
+    /**
+     * GET /v1/sitemap/{id}, returning the header set alongside the body (#2547).
+     *
+     * Same request as `sitemap.get` — same method, path and `RequestOptions`
+     * precedence — and `data` is exactly what `get()` resolves to. `get()`'s own return type
+     * is UNCHANGED; this is an additive sibling, not a replacement.
+     *
+     * The spec documents `X-Sitemap-ID`, `X-Raw-Bytes`, `X-Billing-Multiplier` and
+     * `X-Billable-Bytes` on this endpoint's 200; every one of them is on `headers`.
+     */
+    getWithResponse(id, requestOptions) {
+        return this.client.requestWithResponse('GET', `/v1/sitemap/${id}`, undefined, requestOptions);
     }
 }

package/dist/resources/usage.d.ts

@@ -0,0 +1,36 @@
+import type { ByteKit, RequestOptions } from '../client.js';
+import type { operations } from '../generated/api.js';
+/** 200 payload of GET /v1/usage — current billing period usage summary. */
+export type GetUsageResponse = operations['getUsage']['responses'][200]['content']['application/json'];
+/**
+ * Query params of GET /v1/usage/daily.
+ * Derived from the generated OpenAPI types so it stays in sync with the spec.
+ */
+export type GetUsageDailyParams = NonNullable<operations['getUsageDaily']['parameters']['query']>;
+/** 200 payload of GET /v1/usage/daily — per-day usage breakdown. */
+export type GetUsageDailyResponse = operations['getUsageDaily']['responses'][200]['content']['application/json'];
+/** Query params of GET /v1/usage/by-endpoint. */
+export type GetUsageByEndpointParams = NonNullable<operations['getUsageByEndpoint']['parameters']['query']>;
+/** 200 payload of GET /v1/usage/by-endpoint — per-endpoint bandwidth breakdown. */
+export type GetUsageByEndpointResponse = operations['getUsageByEndpoint']['responses'][200]['content']['application/json'];
+export declare class UsageResource {
+    private readonly client;
+    constructor(client: ByteKit);
+    /**
+     * GET /v1/usage — get current billing period usage.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    get(requestOptions?: RequestOptions): Promise<GetUsageResponse>;
+    /**
+     * GET /v1/usage/daily — get daily usage breakdown.
+     * Default range is the last 30 days; max range is 366 days.
+     */
+    daily(params?: GetUsageDailyParams, requestOptions?: RequestOptions): Promise<GetUsageDailyResponse>;
+    /**
+     * GET /v1/usage/by-endpoint — get per-endpoint bandwidth breakdown.
+     * Default range is the last 30 days; max range is 366 days.
+     */
+    byEndpoint(params?: GetUsageByEndpointParams, requestOptions?: RequestOptions): Promise<GetUsageByEndpointResponse>;
+}

package/dist/resources/usage.js

@@ -0,0 +1,30 @@
+import { toQueryString } from './query-string.js';
+export class UsageResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * GET /v1/usage — get current billing period usage.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    get(requestOptions) {
+        return this.client.request('GET', '/v1/usage', undefined, requestOptions);
+    }
+    /**
+     * GET /v1/usage/daily — get daily usage breakdown.
+     * Default range is the last 30 days; max range is 366 days.
+     */
+    daily(params, requestOptions) {
+        return this.client.request('GET', `/v1/usage/daily${toQueryString(params)}`, undefined, requestOptions);
+    }
+    /**
+     * GET /v1/usage/by-endpoint — get per-endpoint bandwidth breakdown.
+     * Default range is the last 30 days; max range is 366 days.
+     */
+    byEndpoint(params, requestOptions) {
+        return this.client.request('GET', `/v1/usage/by-endpoint${toQueryString(params)}`, undefined, requestOptions);
+    }
+}

package/dist/resources/webhooks.d.ts

@@ -0,0 +1,25 @@
+import type { ByteKit, RequestOptions } from '../client.js';
+import type { operations } from '../generated/api.js';
+import type { WebhookDeliveryId } from '../types.js';
+/**
+ * Query params of GET /v1/webhook-deliveries.
+ * Derived from the generated OpenAPI types so it stays in sync with the spec.
+ */
+export type ListWebhookDeliveriesParams = NonNullable<operations['listWebhookDeliveries']['parameters']['query']>;
+/** 200 payload of GET /v1/webhook-deliveries. */
+export type ListWebhookDeliveriesResponse = operations['listWebhookDeliveries']['responses'][200]['content']['application/json'];
+/** 200 payload of POST /v1/webhook-deliveries/{id}/retry. */
+export type RetryWebhookDeliveryResponse = operations['retryWebhookDelivery']['responses'][200]['content']['application/json'];
+export declare class WebhooksResource {
+    private readonly client;
+    constructor(client: ByteKit);
+    /**
+     * GET /v1/webhook-deliveries — list webhook deliveries.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    list(params?: ListWebhookDeliveriesParams, requestOptions?: RequestOptions): Promise<ListWebhookDeliveriesResponse>;
+    /** POST /v1/webhook-deliveries/{id}/retry — requeue a failed or exhausted delivery. */
+    retry(id: WebhookDeliveryId, requestOptions?: RequestOptions): Promise<RetryWebhookDeliveryResponse>;
+}

package/dist/resources/webhooks.js

@@ -0,0 +1,20 @@
+import { toQueryString } from './query-string.js';
+export class WebhooksResource {
+    client;
+    constructor(client) {
+        this.client = client;
+    }
+    /**
+     * GET /v1/webhook-deliveries — list webhook deliveries.
+     *
+     * `requestOptions` carries the CLIENT-side abort budget (`requestTimeoutMs`) and an
+     * optional caller `signal`; both override the constructor's `timeoutMs` default.
+     */
+    list(params, requestOptions) {
+        return this.client.request('GET', `/v1/webhook-deliveries${toQueryString(params)}`, undefined, requestOptions);
+    }
+    /** POST /v1/webhook-deliveries/{id}/retry — requeue a failed or exhausted delivery. */
+    retry(id, requestOptions) {
+        return this.client.request('POST', `/v1/webhook-deliveries/${id}/retry`, undefined, requestOptions);
+    }
+}

package/dist/types.d.ts

@@ -1,16 +1,16 @@
 /**
- * Prefixed-ID branded types for all RapidCrawl resource identifiers.
+ * Prefixed-ID branded types for all ByteKit resource identifiers.
  *
  * These mirror the `ss_`, `rec_`, `bulk_`, etc. prefixes used at the API
  * boundary (internal rows use raw UUIDs).
  */
 export type ScrapeId = `sc_${string}`;
 export type ScreenshotId = `ss_${string}`;
-export type RecordingId = `rec_${string}`;
 export type BulkId = `bulk_${string}`;
 export type MonitorId = `mon_${string}`;
 export type SitemapId = `sm_${string}`;
 export type ApiKeyId = `ak_${string}`;
+export type WebhookDeliveryId = `wh_${string}`;
 /** Which search index to query. `web` (default), `news`, or `images`. */
 export type SearchType = 'web' | 'news' | 'images';
 /** Recency window for search results (maps to the upstream time filter). */
@@ -66,8 +66,11 @@ export interface SearchResult {
     url: string;
     /** Short text excerpt for the result. Omitted for `images` results. */
     snippet: string;
-    /** Published date when the provider reports one, else `null`. */
-    date: string | null;
+    /**
+     * Published date when the provider reports one, else `null`. Present for
+     * `web`/`news` results; omitted entirely (`undefined`) for `images` results.
+     */
+    date?: string | null;
     /** Publisher / source name. Present for `news` and `images` results. */
     source?: string;
     /** Hosting-page domain of the result. Present only for `images` results. */

package/dist/types.js

@@ -1,5 +1,5 @@
 /**
- * Prefixed-ID branded types for all RapidCrawl resource identifiers.
+ * Prefixed-ID branded types for all ByteKit resource identifiers.
  *
  * These mirror the `ss_`, `rec_`, `bulk_`, etc. prefixes used at the API
  * boundary (internal rows use raw UUIDs).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hunt-labs/bytekit-sdk",
-  "version": "0.2.2",
+  "version": "0.4.0",
   "description": "Official TypeScript SDK for the ByteKit API",
   "license": "MIT",
   "type": "module",