newscatcher-catchall-sdk 1.3.1 → 1.5.0

package/README.md

@@ -11,8 +11,10 @@ The Newscatcher TypeScript library provides convenient access to the Newscatcher
 - [Installation](#installation)
 - [Reference](#reference)
 - [Usage](#usage)
+- [Environments](#environments)
 - [Request and Response Types](#request-and-response-types)
 - [Exception Handling](#exception-handling)
+- [File Uploads](#file-uploads)
 - [Advanced](#advanced)
   - [Subpackage Exports](#subpackage-exports)
   - [Additional Headers](#additional-headers)
@@ -59,6 +61,18 @@ await client.jobs.createJob({
 });
 ```
 
+## Environments
+
+This SDK allows you to configure different environments for API requests.
+
+```typescript
+import { CatchAllApiClient, CatchAllApiEnvironment } from "newscatcher-catchall-sdk";
+
+const client = new CatchAllApiClient({
+    environment: CatchAllApiEnvironment.Default,
+});
+```
+
 ## Request and Response Types
 
 The SDK exports all request and response types as TypeScript interfaces. Simply import them with the
@@ -67,7 +81,7 @@ following namespace:
 ```typescript
 import { CatchAllApi } from "newscatcher-catchall-sdk";
 
-const request: CatchAllApi.InitializeRequestDto = {
+const request: CatchAllApi.GetUserJobsRequest = {
     ...
 };
 ```
@@ -92,6 +106,51 @@ try {
 }
 ```
 
+## File Uploads
+
+You can upload files using the client:
+
+```typescript
+import { createReadStream } from "fs";
+import * as fs from "fs";
+import { CatchAllApiClient } from "newscatcher-catchall-sdk";
+
+const client = new CatchAllApiClient({ apiKey: "YOUR_API_KEY" });
+await client.datasets.createDatasetFromCsv({
+    file: fs.createReadStream("/path/to/your/file"),
+    name: "name"
+});
+```
+The client accepts a variety of types for file upload parameters:
+* Stream types: `fs.ReadStream`, `stream.Readable`, and `ReadableStream`
+* Buffered types: `Buffer`, `Blob`, `File`, `ArrayBuffer`, `ArrayBufferView`, and `Uint8Array`
+
+### Metadata
+
+You can configure metadata when uploading a file:
+```typescript
+const file: Uploadable.WithMetadata = {
+    data: createReadStream("path/to/file"),
+    filename: "my-file",       // optional
+    contentType: "audio/mpeg", // optional
+    contentLength: 1949,       // optional
+};
+```
+
+Alternatively, you can upload a file directly from a file path:
+```typescript
+const file : Uploadable.FromPath = {
+    path: "path/to/file",
+    filename: "my-file",        // optional
+    contentType: "audio/mpeg",  // optional
+    contentLength: 1949,        // optional
+};
+```
+
+The metadata is used to set the `Content-Length`, `Content-Type`, and `Content-Disposition` headers. If not provided, the client will attempt to determine them automatically.
+For example, `fs.ReadStream` has a `path` property which the SDK uses to retrieve the file size from the filesystem without loading it into memory.
+
+
 ## Advanced
 
 ### Subpackage Exports
@@ -303,3 +362,5 @@ On the other hand, contributions to the README are always very welcome!
 - Documentation: [www.newscatcherapi.com/docs/web-search-api](https://www.newscatcherapi.com/docs/web-search-api/get-started/introduction)
 - Support: <support@newscatcherapi.com>
 
+
+

package/dist/cjs/BaseClient.js

@@ -43,8 +43,8 @@ function normalizeClientOptions(options) {
     const headers = (0, headers_js_1.mergeHeaders)({
         "X-Fern-Language": "JavaScript",
         "X-Fern-SDK-Name": "newscatcher-catchall-sdk",
-        "X-Fern-SDK-Version": "1.3.1",
-        "User-Agent": "newscatcher-catchall-sdk/1.3.1",
+        "X-Fern-SDK-Version": "1.5.0",
+        "User-Agent": "newscatcher-catchall-sdk/1.5.0",
         "X-Fern-Runtime": core.RUNTIME.type,
         "X-Fern-Runtime-Version": core.RUNTIME.version,
     }, options === null || options === void 0 ? void 0 : options.headers);

package/dist/cjs/Client.d.ts

@@ -1,3 +1,5 @@
+import { DatasetsClient } from "./api/resources/datasets/client/Client.js";
+import { EntitiesClient } from "./api/resources/entities/client/Client.js";
 import { JobsClient } from "./api/resources/jobs/client/Client.js";
 import { MetaClient } from "./api/resources/meta/client/Client.js";
 import { MonitorsClient } from "./api/resources/monitors/client/Client.js";
@@ -13,10 +15,14 @@ export declare class CatchAllApiClient {
     protected readonly _options: NormalizedClientOptionsWithAuth<CatchAllApiClient.Options>;
     protected _jobs: JobsClient | undefined;
     protected _monitors: MonitorsClient | undefined;
+    protected _entities: EntitiesClient | undefined;
+    protected _datasets: DatasetsClient | undefined;
     protected _meta: MetaClient | undefined;
     constructor(options?: CatchAllApiClient.Options);
     get jobs(): JobsClient;
     get monitors(): MonitorsClient;
+    get entities(): EntitiesClient;
+    get datasets(): DatasetsClient;
     get meta(): MetaClient;
     /**
      * Make a passthrough request using the SDK's configured auth, retry, logging, etc.

package/dist/cjs/Client.js

@@ -44,9 +44,11 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CatchAllApiClient = void 0;
-const Client_js_1 = require("./api/resources/jobs/client/Client.js");
-const Client_js_2 = require("./api/resources/meta/client/Client.js");
-const Client_js_3 = require("./api/resources/monitors/client/Client.js");
+const Client_js_1 = require("./api/resources/datasets/client/Client.js");
+const Client_js_2 = require("./api/resources/entities/client/Client.js");
+const Client_js_3 = require("./api/resources/jobs/client/Client.js");
+const Client_js_4 = require("./api/resources/meta/client/Client.js");
+const Client_js_5 = require("./api/resources/monitors/client/Client.js");
 const BaseClient_js_1 = require("./BaseClient.js");
 const core = __importStar(require("./core/index.js"));
 class CatchAllApiClient {
@@ -55,15 +57,23 @@ class CatchAllApiClient {
     }
     get jobs() {
         var _a;
-        return ((_a = this._jobs) !== null && _a !== void 0 ? _a : (this._jobs = new Client_js_1.JobsClient(this._options)));
+        return ((_a = this._jobs) !== null && _a !== void 0 ? _a : (this._jobs = new Client_js_3.JobsClient(this._options)));
     }
     get monitors() {
         var _a;
-        return ((_a = this._monitors) !== null && _a !== void 0 ? _a : (this._monitors = new Client_js_3.MonitorsClient(this._options)));
+        return ((_a = this._monitors) !== null && _a !== void 0 ? _a : (this._monitors = new Client_js_5.MonitorsClient(this._options)));
+    }
+    get entities() {
+        var _a;
+        return ((_a = this._entities) !== null && _a !== void 0 ? _a : (this._entities = new Client_js_2.EntitiesClient(this._options)));
+    }
+    get datasets() {
+        var _a;
+        return ((_a = this._datasets) !== null && _a !== void 0 ? _a : (this._datasets = new Client_js_1.DatasetsClient(this._options)));
     }
     get meta() {
         var _a;
-        return ((_a = this._meta) !== null && _a !== void 0 ? _a : (this._meta = new Client_js_2.MetaClient(this._options)));
+        return ((_a = this._meta) !== null && _a !== void 0 ? _a : (this._meta = new Client_js_4.MetaClient(this._options)));
     }
     /**
      * Make a passthrough request using the SDK's configured auth, retry, logging, etc.

package/dist/cjs/api/errors/BadRequestError.d.ts

@@ -1,6 +1,5 @@
 import type * as core from "../../core/index.js";
 import * as errors from "../../errors/index.js";
-import type * as CatchAllApi from "../index.js";
 export declare class BadRequestError extends errors.CatchAllApiError {
-    constructor(body: CatchAllApi.Error_, rawResponse?: core.RawResponse);
+    constructor(body?: unknown, rawResponse?: core.RawResponse);
 }

package/dist/cjs/api/errors/UnauthorizedError.d.ts

@@ -0,0 +1,6 @@
+import type * as core from "../../core/index.js";
+import * as errors from "../../errors/index.js";
+import type * as CatchAllApi from "../index.js";
+export declare class UnauthorizedError extends errors.CatchAllApiError {
+    constructor(body: CatchAllApi.Error_, rawResponse?: core.RawResponse);
+}

package/dist/cjs/api/errors/UnauthorizedError.js

@@ -0,0 +1,54 @@
+"use strict";
+// This file was auto-generated by Fern from our API Definition.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UnauthorizedError = void 0;
+const errors = __importStar(require("../../errors/index.js"));
+class UnauthorizedError extends errors.CatchAllApiError {
+    constructor(body, rawResponse) {
+        super({
+            message: "UnauthorizedError",
+            statusCode: 401,
+            body: body,
+            rawResponse: rawResponse,
+        });
+        Object.setPrototypeOf(this, new.target.prototype);
+        if (Error.captureStackTrace) {
+            Error.captureStackTrace(this, this.constructor);
+        }
+        this.name = this.constructor.name;
+    }
+}
+exports.UnauthorizedError = UnauthorizedError;

package/dist/cjs/api/errors/index.d.ts

@@ -1,4 +1,5 @@
 export * from "./BadRequestError.js";
 export * from "./ForbiddenError.js";
 export * from "./NotFoundError.js";
+export * from "./UnauthorizedError.js";
 export * from "./UnprocessableEntityError.js";

package/dist/cjs/api/errors/index.js

@@ -17,4 +17,5 @@ Object.defineProperty(exports, "__esModule", { value: true });
 __exportStar(require("./BadRequestError.js"), exports);
 __exportStar(require("./ForbiddenError.js"), exports);
 __exportStar(require("./NotFoundError.js"), exports);
+__exportStar(require("./UnauthorizedError.js"), exports);
 __exportStar(require("./UnprocessableEntityError.js"), exports);

package/dist/cjs/api/resources/datasets/client/Client.d.ts

@@ -0,0 +1,245 @@
+import type { BaseClientOptions, BaseRequestOptions } from "../../../../BaseClient.js";
+import { type NormalizedClientOptionsWithAuth } from "../../../../BaseClient.js";
+import * as core from "../../../../core/index.js";
+import * as CatchAllApi from "../../../index.js";
+export declare namespace DatasetsClient {
+    type Options = BaseClientOptions;
+    interface RequestOptions extends BaseRequestOptions {
+    }
+}
+/**
+ * Operations to create and manage datasets of entities.
+ *
+ * A dataset is a named collection of entities — think of it as a watchlist or
+ * portfolio. Connect a dataset to a job via `connected_dataset_ids` to activate
+ * Company Watchlist. Datasets can be reused across multiple jobs and monitors.
+ */
+export declare class DatasetsClient {
+    protected readonly _options: NormalizedClientOptionsWithAuth<DatasetsClient.Options>;
+    constructor(options?: DatasetsClient.Options);
+    /**
+     * Returns a paginated list of datasets belonging to the authenticated
+     * organization. Supports filtering by status and sorting by name,
+     * status, or creation date.
+     *
+     * @param {CatchAllApi.ListDatasetsRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.ForbiddenError}
+     *
+     * @example
+     *     await client.datasets.listDatasets({
+     *         search: "Portfolio"
+     *     })
+     */
+    listDatasets(request?: CatchAllApi.ListDatasetsRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<CatchAllApi.DatasetListResponse>;
+    private __listDatasets;
+    /**
+     * Creates a new dataset from a list of existing entity IDs.
+     *
+     * If any of the provided entity IDs do not exist or do not belong to
+     * your organization, the request fails with `400`. All entity IDs must
+     * be valid before the dataset is created.
+     *
+     * To create a dataset and entities in one step, use the [`Create dataset from CSV`](https://www.newscatcherapi.com/docs/web-search-api/api-reference/datasets/create-dataset-from-csv)
+     * endpoint instead.
+     *
+     * @param {CatchAllApi.CreateDatasetRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.BadRequestError}
+     * @throws {@link CatchAllApi.ForbiddenError}
+     * @throws {@link CatchAllApi.UnprocessableEntityError}
+     *
+     * @example
+     *     await client.datasets.createDataset({
+     *         name: "My Portfolio",
+     *         description: "Companies in our investment portfolio",
+     *         entity_ids: ["854198fa-f702-49db-a381-0427fa87f173", "a1b2c3d4-e5f6-7890-abcd-ef1234567890"]
+     *     })
+     */
+    createDataset(request: CatchAllApi.CreateDatasetRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<CatchAllApi.DatasetResponse>;
+    private __createDataset;
+    /**
+     * Creates a new dataset by uploading a CSV file. Each row in the CSV
+     * becomes an entity. The `name` column is required; all other columns
+     * are optional.
+     *
+     * **CSV format:**
+     * ```csv
+     * name,description,domain,alternative_names,key_persons
+     * NewsCatcher,"AI-powered news data provider",newscatcherapi.com,"NC;NewsCatcher API","Artem Bugara;Maksym Sugonyaka"
+     * OpenAI,"Artificial intelligence research company",openai.com,"Open AI","Sam Altman"
+     * ```
+     *
+     * Use semicolons (`;`) to separate multiple values in `alternative_names` and `key_persons`. Rows with empty `name` are skipped and reported in `validation_report`.
+     *
+     * **Note**: The response shape differs from the JSON dataset creation endpoint: it returns `dataset_id` (not `id`) and includes a `validation_report` with details on skipped rows.
+     *
+     * @param {CatchAllApi.CreateDatasetFromCsvRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.ForbiddenError}
+     * @throws {@link CatchAllApi.UnprocessableEntityError}
+     *
+     * @example
+     *     import { createReadStream } from "fs";
+     *     await client.datasets.createDatasetFromCsv({
+     *         file: fs.createReadStream("/path/to/your/file"),
+     *         name: "name"
+     *     })
+     */
+    createDatasetFromCsv(request: CatchAllApi.CreateDatasetFromCsvRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<CatchAllApi.CreateDatasetCsvResponse>;
+    private __createDatasetFromCsv;
+    /**
+     * Returns a single dataset by ID including entity count and current status.
+     *
+     * @param {CatchAllApi.GetDatasetRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.ForbiddenError}
+     * @throws {@link CatchAllApi.NotFoundError}
+     *
+     * @example
+     *     await client.datasets.getDataset({
+     *         dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
+     *     })
+     */
+    getDataset(request: CatchAllApi.GetDatasetRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<CatchAllApi.DatasetResponse>;
+    private __getDataset;
+    /**
+     * Permanently deletes a dataset. The entities within the dataset are
+     * not deleted — only the dataset itself. This operation cannot be
+     * undone.
+     *
+     * @param {CatchAllApi.DeleteDatasetRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.ForbiddenError}
+     * @throws {@link CatchAllApi.NotFoundError}
+     *
+     * @example
+     *     await client.datasets.deleteDataset({
+     *         dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
+     *     })
+     */
+    deleteDataset(request: CatchAllApi.DeleteDatasetRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<void>;
+    private __deleteDataset;
+    /**
+     * Updates the name or description of a dataset.
+     *
+     * @param {CatchAllApi.UpdateDatasetRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.ForbiddenError}
+     * @throws {@link CatchAllApi.NotFoundError}
+     * @throws {@link CatchAllApi.UnprocessableEntityError}
+     *
+     * @example
+     *     await client.datasets.updateDataset({
+     *         dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2",
+     *         name: "My Portfolio (updated)",
+     *         description: "Updated Q1 2026 watchlist"
+     *     })
+     */
+    updateDataset(request: CatchAllApi.UpdateDatasetRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<CatchAllApi.DatasetResponse>;
+    private __updateDataset;
+    /**
+     * Returns a paginated list of entities in a dataset. Supports filtering by status and entity type.
+     *
+     * @param {CatchAllApi.ListEntitiesInDatasetRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.ForbiddenError}
+     * @throws {@link CatchAllApi.NotFoundError}
+     *
+     * @example
+     *     await client.datasets.listEntitiesInDataset({
+     *         dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
+     *     })
+     */
+    listEntitiesInDataset(request: CatchAllApi.ListEntitiesInDatasetRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<CatchAllApi.DatasetEntityListResponse>;
+    private __listEntitiesInDataset;
+    /**
+     * Adds one or more existing entities to a dataset. Returns the number of entities added.
+     *
+     * @param {CatchAllApi.AddEntitiesToDatasetRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.ForbiddenError}
+     * @throws {@link CatchAllApi.NotFoundError}
+     * @throws {@link CatchAllApi.UnprocessableEntityError}
+     *
+     * @example
+     *     await client.datasets.addEntitiesToDataset({
+     *         dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2",
+     *         body: {
+     *             entity_ids: ["854198fa-f702-49db-a381-0427fa87f173"]
+     *         }
+     *     })
+     */
+    addEntitiesToDataset(request: CatchAllApi.AddEntitiesToDatasetRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<CatchAllApi.ManageEntitiesResponse>;
+    private __addEntitiesToDataset;
+    /**
+     * Removes one or more entities from a dataset. The entities themselves
+     * are not deleted — they are only removed from this dataset. Returns
+     * the number of entities removed.
+     *
+     * @param {CatchAllApi.RemoveEntitiesFromDatasetRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.ForbiddenError}
+     * @throws {@link CatchAllApi.NotFoundError}
+     * @throws {@link CatchAllApi.UnprocessableEntityError}
+     *
+     * @example
+     *     await client.datasets.removeEntitiesFromDataset({
+     *         dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2",
+     *         body: {
+     *             entity_ids: ["854198fa-f702-49db-a381-0427fa87f173"]
+     *         }
+     *     })
+     */
+    removeEntitiesFromDataset(request: CatchAllApi.RemoveEntitiesFromDatasetRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<CatchAllApi.ManageEntitiesResponse>;
+    private __removeEntitiesFromDataset;
+    /**
+     * Returns the full status change history for a dataset, ordered
+     * chronologically from oldest to newest.
+     *
+     * @param {CatchAllApi.GetDatasetStatusHistoryRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.ForbiddenError}
+     * @throws {@link CatchAllApi.NotFoundError}
+     *
+     * @example
+     *     await client.datasets.getDatasetStatusHistory({
+     *         dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
+     *     })
+     */
+    getDatasetStatusHistory(request: CatchAllApi.GetDatasetStatusHistoryRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<CatchAllApi.DatasetStatusHistoryResponse>;
+    private __getDatasetStatusHistory;
+    /**
+     * Appends new companies to an existing dataset by uploading a CSV file.
+     * Uses the same CSV format as the dataset creation endpoint.
+     *
+     * The response omits `dataset_name` compared to the create-from-CSV
+     * endpoint since the dataset already exists.
+     *
+     * @param {CatchAllApi.UploadCsvToDatasetRequest} request
+     * @param {DatasetsClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link CatchAllApi.ForbiddenError}
+     * @throws {@link CatchAllApi.NotFoundError}
+     * @throws {@link CatchAllApi.UnprocessableEntityError}
+     *
+     * @example
+     *     import { createReadStream } from "fs";
+     *     await client.datasets.uploadCsvToDataset({
+     *         file: fs.createReadStream("/path/to/your/file"),
+     *         dataset_id: "ccabb755-afc2-4047-b84c-78d1f23d49b2"
+     *     })
+     */
+    uploadCsvToDataset(request: CatchAllApi.UploadCsvToDatasetRequest, requestOptions?: DatasetsClient.RequestOptions): core.HttpResponsePromise<CatchAllApi.UploadCsvToDatasetResponse>;
+    private __uploadCsvToDataset;
+}