@censys/platform-sdk 0.4.3

package/src/sdk/collections.ts

@@ -0,0 +1,153 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { collectionsAggregate } from "../funcs/collectionsAggregate.js";
+import { collectionsCreate } from "../funcs/collectionsCreate.js";
+import { collectionsDelete } from "../funcs/collectionsDelete.js";
+import { collectionsGet } from "../funcs/collectionsGet.js";
+import { collectionsList } from "../funcs/collectionsList.js";
+import { collectionsListEvents } from "../funcs/collectionsListEvents.js";
+import { collectionsSearch } from "../funcs/collectionsSearch.js";
+import { collectionsUpdate } from "../funcs/collectionsUpdate.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as operations from "../models/operations/index.js";
+import { unwrapAsync } from "../types/fp.js";
+
+export class Collections extends ClientSDK {
+  /**
+   * List collections
+   *
+   * @remarks
+   * List all collections for an organization. Retrieved information includes collection ID, name, query, description, status, and asset count.
+   */
+  async list(
+    request: operations.V3CollectionsCrudListRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3CollectionsCrudListResponse> {
+    return unwrapAsync(collectionsList(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Create a collection
+   *
+   * @remarks
+   * Create a new collection.
+   */
+  async create(
+    request: operations.V3CollectionsCrudCreateRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3CollectionsCrudCreateResponse> {
+    return unwrapAsync(collectionsCreate(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Delete a collection
+   *
+   * @remarks
+   * Delete a collection.
+   */
+  async delete(
+    request: operations.V3CollectionsCrudDeleteRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3CollectionsCrudDeleteResponse | undefined> {
+    return unwrapAsync(collectionsDelete(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get a collection
+   *
+   * @remarks
+   * Retrieve information about a collection. Retrieved information includes its name, query, description, status, and asset count.
+   */
+  async get(
+    request: operations.V3CollectionsCrudGetRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3CollectionsCrudGetResponse> {
+    return unwrapAsync(collectionsGet(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Update a collection
+   *
+   * @remarks
+   * Update a collection's name, description, and/or query.
+   */
+  async update(
+    request: operations.V3CollectionsCrudUpdateRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3CollectionsCrudUpdateResponse> {
+    return unwrapAsync(collectionsUpdate(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get a collection's events
+   *
+   * @remarks
+   * Retrieve the event history for a collection. This includes the addition or removal of assets as well as collection status changes.
+   */
+  async listEvents(
+    request: operations.V3CollectionsListEventsRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3CollectionsListEventsResponse> {
+    return unwrapAsync(collectionsListEvents(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Aggregate results for a search query within a collection
+   *
+   * @remarks
+   * Aggregate results for a Platform search query that targets a collection's assets. This functionality is equivalent to the [Report Builder](https://docs.censys.com/docs/platform-report-builder#/) in the Platform web UI.
+   */
+  async aggregate(
+    request: operations.V3CollectionsSearchAggregateRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3CollectionsSearchAggregateResponse> {
+    return unwrapAsync(collectionsAggregate(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Run a search query within a collection
+   *
+   * @remarks
+   * Run a search query across a collection's assets. Reference the [documentation on Censys Query Language](https://docs.censys.com/docs/censys-query-language#/) for information about query syntax.
+   */
+  async search(
+    request: operations.V3CollectionsSearchQueryRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3CollectionsSearchQueryResponse> {
+    return unwrapAsync(collectionsSearch(
+      this,
+      request,
+      options,
+    ));
+  }
+}

package/src/sdk/globaldata.ts

@@ -0,0 +1,171 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { globalDataAggregate } from "../funcs/globalDataAggregate.js";
+import { globalDataGetCertificate } from "../funcs/globalDataGetCertificate.js";
+import { globalDataGetCertificates } from "../funcs/globalDataGetCertificates.js";
+import { globalDataGetHost } from "../funcs/globalDataGetHost.js";
+import { globalDataGetHosts } from "../funcs/globalDataGetHosts.js";
+import { globalDataGetHostTimeline } from "../funcs/globalDataGetHostTimeline.js";
+import { globalDataGetWebProperties } from "../funcs/globalDataGetWebProperties.js";
+import { globalDataGetWebProperty } from "../funcs/globalDataGetWebProperty.js";
+import { globalDataSearch } from "../funcs/globalDataSearch.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as operations from "../models/operations/index.js";
+import { unwrapAsync } from "../types/fp.js";
+
+export class GlobalData extends ClientSDK {
+  /**
+   * Get multiple certificates
+   *
+   * @remarks
+   * Retrieve information about multiple certificates. A certificate ID is its SHA-256 fingerprint in the Censys dataset.
+   */
+  async getCertificates(
+    request: operations.V3GlobaldataAssetCertificateListRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3GlobaldataAssetCertificateListResponse> {
+    return unwrapAsync(globalDataGetCertificates(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get a certificate
+   *
+   * @remarks
+   * Retrieve information about a single certificate. A certificate ID is its SHA-256 fingerprint in the Censys dataset.
+   */
+  async getCertificate(
+    request: operations.V3GlobaldataAssetCertificateRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3GlobaldataAssetCertificateResponse> {
+    return unwrapAsync(globalDataGetCertificate(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get multiple hosts
+   *
+   * @remarks
+   * Retrieve information about multiple hosts. A host ID is its IP address.
+   */
+  async getHosts(
+    request: operations.V3GlobaldataAssetHostListRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3GlobaldataAssetHostListResponse> {
+    return unwrapAsync(globalDataGetHosts(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get a host
+   *
+   * @remarks
+   * Retrieve information about a single host. A host ID is its IP address.
+   */
+  async getHost(
+    request: operations.V3GlobaldataAssetHostRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3GlobaldataAssetHostResponse> {
+    return unwrapAsync(globalDataGetHost(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get host event history
+   *
+   * @remarks
+   * Retrieve event history for a host. A host ID is its IP address.
+   */
+  async getHostTimeline(
+    request: operations.V3GlobaldataAssetHostTimelineRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3GlobaldataAssetHostTimelineResponse> {
+    return unwrapAsync(globalDataGetHostTimeline(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get multiple web properties
+   *
+   * @remarks
+   * Retrieve information about multiple web properties. Web properties are identified using a combination of a hostname and port joined with a colon, such as `platform.censys.io:80`.
+   */
+  async getWebProperties(
+    request: operations.V3GlobaldataAssetWebpropertyListRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3GlobaldataAssetWebpropertyListResponse> {
+    return unwrapAsync(globalDataGetWebProperties(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Get a web property
+   *
+   * @remarks
+   * Retrieve information about a single web property. Web properties are identified using a combination of a hostname and port joined with a colon, such as `platform.censys.io:80`.
+   */
+  async getWebProperty(
+    request: operations.V3GlobaldataAssetWebpropertyRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3GlobaldataAssetWebpropertyResponse> {
+    return unwrapAsync(globalDataGetWebProperty(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Aggregate results for a search query
+   *
+   * @remarks
+   * Aggregate results for a Platform search query. This functionality is equivalent to the [Report Builder](https://docs.censys.com/docs/platform-report-builder#/) in the Platform web UI.
+   */
+  async aggregate(
+    request: operations.V3GlobaldataSearchAggregateRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3GlobaldataSearchAggregateResponse> {
+    return unwrapAsync(globalDataAggregate(
+      this,
+      request,
+      options,
+    ));
+  }
+
+  /**
+   * Run a search query
+   *
+   * @remarks
+   * Run a search query across Censys data. Reference the [documentation on Censys Query Language](https://docs.censys.com/docs/censys-query-language#/) for information about query syntax.
+   */
+  async search(
+    request: operations.V3GlobaldataSearchQueryRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3GlobaldataSearchQueryResponse> {
+    return unwrapAsync(globalDataSearch(
+      this,
+      request,
+      options,
+    ));
+  }
+}

package/src/sdk/index.ts

@@ -0,0 +1,5 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export * from "./sdk.js";

package/src/sdk/sdk.ts

@@ -0,0 +1,25 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { ClientSDK } from "../lib/sdks.js";
+import { Collections } from "./collections.js";
+import { GlobalData } from "./globaldata.js";
+import { ThreatHunting } from "./threathunting.js";
+
+export class SDK extends ClientSDK {
+  private _collections?: Collections;
+  get collections(): Collections {
+    return (this._collections ??= new Collections(this._options));
+  }
+
+  private _globalData?: GlobalData;
+  get globalData(): GlobalData {
+    return (this._globalData ??= new GlobalData(this._options));
+  }
+
+  private _threatHunting?: ThreatHunting;
+  get threatHunting(): ThreatHunting {
+    return (this._threatHunting ??= new ThreatHunting(this._options));
+  }
+}

package/src/sdk/threathunting.ts

@@ -0,0 +1,27 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { threatHuntingValueCounts } from "../funcs/threatHuntingValueCounts.js";
+import { ClientSDK, RequestOptions } from "../lib/sdks.js";
+import * as operations from "../models/operations/index.js";
+import { unwrapAsync } from "../types/fp.js";
+
+export class ThreatHunting extends ClientSDK {
+  /**
+   * CensEye: Retrieve value counts to discover pivots
+   *
+   * @remarks
+   * Get counts of web assets for specific field-value pairs and combinations of field-value pairs. This is similar to the [CensEye functionality](https://docs.censys.com/docs/platform-threat-hunting-use-censeye-to-build-detections#/) available in the Platform web UI, but it allows you to define specific fields of interest rather than the [default fields](https://docs.censys.com/docs/platform-threat-hunting-use-censeye-to-build-detections#default-pivot-fields) leveraged by the tool in the UI.<br><br>Each array can only target fields within the same nested object. For example, you can combine `host.services.port=80` and `host.services.protocol=SSH` in the same array, but you cannot combine `host.services.port=80` and `host.location.country=”United States”` in the same array. You can input multiple arrays of objects in each API call.<br><br>To use this endpoint, your organization must have access to the Threat Hunting Module. This endpoint costs 1 credit per count condition (array of objects) included in the API call.
+   */
+  async valueCounts(
+    request: operations.V3ThreathuntingValueCountsRequest,
+    options?: RequestOptions,
+  ): Promise<operations.V3ThreathuntingValueCountsResponse> {
+    return unwrapAsync(threatHuntingValueCounts(
+      this,
+      request,
+      options,
+    ));
+  }
+}

package/src/types/async.ts

@@ -0,0 +1,68 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export type APICall =
+  | {
+      status: "complete";
+      request: Request;
+      response: Response;
+    }
+  | {
+      status: "request-error";
+      request: Request;
+      response?: undefined;
+    }
+  | {
+      status: "invalid";
+      request?: undefined;
+      response?: undefined;
+    };
+
+export class APIPromise<T> implements Promise<T> {
+  readonly #promise: Promise<[T, APICall]>;
+  readonly #unwrapped: Promise<T>;
+
+  readonly [Symbol.toStringTag] = "APIPromise";
+
+  constructor(p: [T, APICall] | Promise<[T, APICall]>) {
+    this.#promise = p instanceof Promise ? p : Promise.resolve(p);
+    this.#unwrapped =
+      p instanceof Promise
+        ? this.#promise.then(([value]) => value)
+        : Promise.resolve(p[0]);
+  }
+
+  then<TResult1 = T, TResult2 = never>(
+    onfulfilled?:
+      | ((value: T) => TResult1 | PromiseLike<TResult1>)
+      | null
+      | undefined,
+    onrejected?:
+      | ((reason: any) => TResult2 | PromiseLike<TResult2>)
+      | null
+      | undefined,
+  ): Promise<TResult1 | TResult2> {
+    return this.#promise.then(
+      onfulfilled ? ([value]) => onfulfilled(value) : void 0,
+      onrejected,
+    );
+  }
+
+  catch<TResult = never>(
+    onrejected?:
+      | ((reason: any) => TResult | PromiseLike<TResult>)
+      | null
+      | undefined,
+  ): Promise<T | TResult> {
+    return this.#unwrapped.catch(onrejected);
+  }
+
+  finally(onfinally?: (() => void) | null | undefined): Promise<T> {
+    return this.#unwrapped.finally(onfinally);
+  }
+
+  $inspect(): Promise<[T, APICall]> {
+    return this.#promise;
+  }
+}

package/src/types/blobs.ts

@@ -0,0 +1,31 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+export const blobLikeSchema: z.ZodType<Blob, z.ZodTypeDef, Blob> =
+  z.custom<Blob>(isBlobLike, {
+    message: "expected a Blob, File or Blob-like object",
+    fatal: true,
+  });
+
+export function isBlobLike(val: unknown): val is Blob {
+  if (val instanceof Blob) {
+    return true;
+  }
+
+  if (typeof val !== "object" || val == null || !(Symbol.toStringTag in val)) {
+    return false;
+  }
+
+  const name = val[Symbol.toStringTag];
+  if (typeof name !== "string") {
+    return false;
+  }
+  if (name !== "Blob" && name !== "File") {
+    return false;
+  }
+
+  return "stream" in val && typeof val.stream === "function";
+}

package/src/types/constdatetime.ts

@@ -0,0 +1,15 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import * as z from "zod";
+
+export function constDateTime(
+  val: string,
+): z.ZodType<string, z.ZodTypeDef, unknown> {
+  return z.custom<string>((v) => {
+    return (
+      typeof v === "string" && new Date(v).getTime() === new Date(val).getTime()
+    );
+  }, `Value must be equivalent to ${val}`);
+}

package/src/types/enums.ts

@@ -0,0 +1,16 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+declare const __brand: unique symbol;
+export type Unrecognized<T> = T & { [__brand]: "unrecognized" };
+
+export function catchUnrecognizedEnum<T>(value: T): Unrecognized<T> {
+  return value as Unrecognized<T>;
+}
+
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+export type ClosedEnum<T> = T[keyof T];
+export type OpenEnum<T> =
+  | Prettify<T[keyof T]>
+  | Unrecognized<T[keyof T] extends number ? number : string>;

package/src/types/fp.ts

@@ -0,0 +1,50 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+/**
+ * A monad that captures the result of a function call or an error if it was not
+ * successful. Railway programming, enabled by this type, can be a nicer
+ * alternative to traditional exception throwing because it allows functions to
+ * declare all _known_ errors with static types and then check for them
+ * exhaustively in application code. Thrown exception have a type of `unknown`
+ * and break out of regular control flow of programs making them harder to
+ * inspect and more verbose work with due to try-catch blocks.
+ */
+export type Result<T, E = unknown> =
+  | { ok: true; value: T; error?: never }
+  | { ok: false; value?: never; error: E };
+
+export function OK<V>(value: V): Result<V, never> {
+  return { ok: true, value };
+}
+
+export function ERR<E>(error: E): Result<never, E> {
+  return { ok: false, error };
+}
+
+/**
+ * unwrap is a convenience function for extracting a value from a result or
+ * throwing if there was an error.
+ */
+export function unwrap<T>(r: Result<T, unknown>): T {
+  if (!r.ok) {
+    throw r.error;
+  }
+  return r.value;
+}
+
+/**
+ * unwrapAsync is a convenience function for resolving a value from a Promise
+ * of a result or rejecting if an error occurred.
+ */
+export async function unwrapAsync<T>(
+  pr: Promise<Result<T, unknown>>,
+): Promise<T> {
+  const r = await pr;
+  if (!r.ok) {
+    throw r.error;
+  }
+
+  return r.value;
+}

package/src/types/index.ts

@@ -0,0 +1,11 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+export { blobLikeSchema, isBlobLike } from "./blobs.js";
+export { catchUnrecognizedEnum } from "./enums.js";
+export type { ClosedEnum, OpenEnum, Unrecognized } from "./enums.js";
+export type { Result } from "./fp.js";
+export type { PageIterator, Paginator } from "./operations.js";
+export { createPageIterator } from "./operations.js";
+export { RFCDate } from "./rfcdate.js";

package/src/types/operations.ts

@@ -0,0 +1,105 @@
+/*
+ * Code generated by Speakeasy (https://speakeasy.com). DO NOT EDIT.
+ */
+
+import { Result } from "./fp.js";
+
+export type Paginator<V> = () => Promise<V & { next: Paginator<V> }> | null;
+
+export type PageIterator<V, PageState = unknown> = V & {
+  next: Paginator<V>;
+  [Symbol.asyncIterator]: () => AsyncIterableIterator<V>;
+  "~next"?: PageState | undefined;
+};
+
+export function createPageIterator<V>(
+  page: V & { next: Paginator<V> },
+  halt: (v: V) => boolean,
+): {
+  [Symbol.asyncIterator]: () => AsyncIterableIterator<V>;
+} {
+  return {
+    [Symbol.asyncIterator]: async function* paginator() {
+      yield page;
+      if (halt(page)) {
+        return;
+      }
+
+      let p: typeof page | null = page;
+      for (p = await p.next(); p != null; p = await p.next()) {
+        yield p;
+        if (halt(p)) {
+          return;
+        }
+      }
+    },
+  };
+}
+
+/**
+ * This utility create a special iterator that yields a single value and
+ * terminates. It is useful in paginated SDK functions that have early return
+ * paths when things go wrong.
+ */
+export function haltIterator<V extends object>(
+  v: V,
+): PageIterator<V, undefined> {
+  return {
+    ...v,
+    next: () => null,
+    [Symbol.asyncIterator]: async function* paginator() {
+      yield v;
+    },
+  };
+}
+
+/**
+ * Converts an async iterator of `Result<V, E>` into an async iterator of `V`.
+ * When error results occur, the underlying error value is thrown.
+ */
+export async function unwrapResultIterator<V, PageState>(
+  iteratorPromise: Promise<PageIterator<Result<V, unknown>, PageState>>,
+): Promise<PageIterator<V, PageState>> {
+  const resultIter = await iteratorPromise;
+
+  if (!resultIter.ok) {
+    throw resultIter.error;
+  }
+
+  return {
+    ...resultIter.value,
+    next: unwrapPaginator(resultIter.next),
+    "~next": resultIter["~next"],
+    [Symbol.asyncIterator]: async function* paginator() {
+      for await (const page of resultIter) {
+        if (!page.ok) {
+          throw page.error;
+        }
+        yield page.value;
+      }
+    },
+  };
+}
+
+function unwrapPaginator<V>(
+  paginator: Paginator<Result<V, unknown>>,
+): Paginator<V> {
+  return () => {
+    const nextResult = paginator();
+    if (nextResult == null) {
+      return null;
+    }
+    return nextResult.then((res) => {
+      if (!res.ok) {
+        throw res.error;
+      }
+      const out = {
+        ...res.value,
+        next: unwrapPaginator(res.next),
+      };
+      return out;
+    });
+  };
+}
+
+export const URL_OVERRIDE = Symbol("URL_OVERRIDE");