@predictorsdk/client 0.8.0 → 0.9.0

package/dist/Client.d.ts

@@ -46,6 +46,21 @@ export declare class PredictorSDKClient {
      */
     getMarkets(request?: PredictorSDK.GetMarketsRequest, requestOptions?: PredictorSDKClient.RequestOptions): core.HttpResponsePromise<PredictorSDK.MarketsListResponse>;
     private __getMarkets;
+    /**
+     * Returns the canonical top-level categories that can be used to filter unified market discovery with `GET /v1/markets?category=...`. Categories are PredictorSDK-normalized buckets, not provider-native tags. Sports is one category among many; sport/league facets may be added later as deeper filters without changing this top-level list.
+     *
+     * @param {PredictorSDKClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link PredictorSDK.UnauthorizedError}
+     * @throws {@link PredictorSDK.PaymentRequiredError}
+     * @throws {@link PredictorSDK.ForbiddenError}
+     * @throws {@link PredictorSDK.TooManyRequestsError}
+     *
+     * @example
+     *     await client.getCategories()
+     */
+    getCategories(requestOptions?: PredictorSDKClient.RequestOptions): core.HttpResponsePromise<PredictorSDK.CategoriesResponse>;
+    private __getCategories;
     /**
      * Returns a single market across the six supported platforms (Kalshi, Polymarket, Predict, SX Bet, Hyperliquid, AlphaArcade). The `market_id` is either the composite form returned by `GET /v1/markets` (`{provider}:{native_id}`, e.g. `kalshi:KXNBA-26-SAS`) or the platform-native identifier. Composite IDs dispatch unambiguously by prefix. Native IDs are routed by format inference: Kalshi tickers match the all-caps-with-hyphens shape (`KX…-…`); SX Bet hashes match `0x` + 64 hex characters; numeric ids and kebab-case slugs are shared shape between Polymarket and Predict and probe Polymarket first, falling back to Predict on 404. Hyperliquid integer outcome ids collide with Polymarket/Predict numeric ids and are deliberately not inferred — route them via the composite form (`hyperliquid:<id>`) or `?platform=hyperliquid` (alias `hl`). AlphaArcade market ids are ULIDs (26-char Crockford base32, e.g. `01KQV5TQ9CE20WPEVJZX2ETNQD`); like Hyperliquid they are not inferred in v1 — route them via the composite form (`alpha-arcade:<ulid>`) or `?platform=alpha-arcade` (alias `aa`). Pass `?platform=` explicitly to skip the probe.
      *

package/dist/Client.js

@@ -153,10 +153,16 @@ export class PredictorSDKClient {
         return core.HttpResponsePromise.fromPromise(this.__getMarkets(request, requestOptions));
     }
     async __getMarkets(request = {}, requestOptions) {
-        const { limit, cursor } = request;
+        const { limit, cursor, category } = request;
         const _queryParams = {
             limit,
             cursor,
+            category: category != null
+                ? serializers.MarketCategory.jsonOrThrow(category, {
+                    unrecognizedObjectKeys: "strip",
+                    omitUndefined: true,
+                })
+                : undefined,
         };
         const _authRequest = await this._options.authProvider.getAuthRequest();
         const _headers = mergeHeaders(_authRequest.headers, this._options?.headers, requestOptions?.headers);
@@ -249,6 +255,94 @@ export class PredictorSDKClient {
         }
         return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/markets");
     }
+    /**
+     * Returns the canonical top-level categories that can be used to filter unified market discovery with `GET /v1/markets?category=...`. Categories are PredictorSDK-normalized buckets, not provider-native tags. Sports is one category among many; sport/league facets may be added later as deeper filters without changing this top-level list.
+     *
+     * @param {PredictorSDKClient.RequestOptions} requestOptions - Request-specific configuration.
+     *
+     * @throws {@link PredictorSDK.UnauthorizedError}
+     * @throws {@link PredictorSDK.PaymentRequiredError}
+     * @throws {@link PredictorSDK.ForbiddenError}
+     * @throws {@link PredictorSDK.TooManyRequestsError}
+     *
+     * @example
+     *     await client.getCategories()
+     */
+    getCategories(requestOptions) {
+        return core.HttpResponsePromise.fromPromise(this.__getCategories(requestOptions));
+    }
+    async __getCategories(requestOptions) {
+        const _authRequest = await this._options.authProvider.getAuthRequest();
+        const _headers = mergeHeaders(_authRequest.headers, this._options?.headers, requestOptions?.headers);
+        const _response = await core.fetcher({
+            url: core.url.join((await core.Supplier.get(this._options.baseUrl)) ??
+                (await core.Supplier.get(this._options.environment)) ??
+                environments.PredictorSDKEnvironment.Production, "v1/categories"),
+            method: "GET",
+            headers: _headers,
+            queryString: core.url.queryBuilder().mergeAdditional(requestOptions?.queryParams).build(),
+            timeoutMs: (requestOptions?.timeoutInSeconds ?? this._options?.timeoutInSeconds ?? 60) * 1000,
+            maxRetries: requestOptions?.maxRetries ?? this._options?.maxRetries,
+            abortSignal: requestOptions?.abortSignal,
+            fetchFn: this._options?.fetch,
+            logging: this._options.logging,
+        });
+        if (_response.ok) {
+            return {
+                data: serializers.CategoriesResponse.parseOrThrow(_response.body, {
+                    unrecognizedObjectKeys: "passthrough",
+                    allowUnrecognizedUnionMembers: true,
+                    allowUnrecognizedEnumValues: true,
+                    skipValidation: true,
+                    breadcrumbsPrefix: ["response"],
+                }),
+                rawResponse: _response.rawResponse,
+            };
+        }
+        if (_response.error.reason === "status-code") {
+            switch (_response.error.statusCode) {
+                case 401:
+                    throw new PredictorSDK.UnauthorizedError(serializers.ErrorResponse.parseOrThrow(_response.error.body, {
+                        unrecognizedObjectKeys: "passthrough",
+                        allowUnrecognizedUnionMembers: true,
+                        allowUnrecognizedEnumValues: true,
+                        skipValidation: true,
+                        breadcrumbsPrefix: ["response"],
+                    }), _response.rawResponse);
+                case 402:
+                    throw new PredictorSDK.PaymentRequiredError(serializers.PaymentRequiredErrorBody.parseOrThrow(_response.error.body, {
+                        unrecognizedObjectKeys: "passthrough",
+                        allowUnrecognizedUnionMembers: true,
+                        allowUnrecognizedEnumValues: true,
+                        skipValidation: true,
+                        breadcrumbsPrefix: ["response"],
+                    }), _response.rawResponse);
+                case 403:
+                    throw new PredictorSDK.ForbiddenError(serializers.ErrorResponse.parseOrThrow(_response.error.body, {
+                        unrecognizedObjectKeys: "passthrough",
+                        allowUnrecognizedUnionMembers: true,
+                        allowUnrecognizedEnumValues: true,
+                        skipValidation: true,
+                        breadcrumbsPrefix: ["response"],
+                    }), _response.rawResponse);
+                case 429:
+                    throw new PredictorSDK.TooManyRequestsError(serializers.ErrorResponse.parseOrThrow(_response.error.body, {
+                        unrecognizedObjectKeys: "passthrough",
+                        allowUnrecognizedUnionMembers: true,
+                        allowUnrecognizedEnumValues: true,
+                        skipValidation: true,
+                        breadcrumbsPrefix: ["response"],
+                    }), _response.rawResponse);
+                default:
+                    throw new errors.PredictorSDKError({
+                        statusCode: _response.error.statusCode,
+                        body: _response.error.body,
+                        rawResponse: _response.rawResponse,
+                    });
+            }
+        }
+        return handleNonStatusCodeError(_response.error, _response.rawResponse, "GET", "/v1/categories");
+    }
     /**
      * Returns a single market across the six supported platforms (Kalshi, Polymarket, Predict, SX Bet, Hyperliquid, AlphaArcade). The `market_id` is either the composite form returned by `GET /v1/markets` (`{provider}:{native_id}`, e.g. `kalshi:KXNBA-26-SAS`) or the platform-native identifier. Composite IDs dispatch unambiguously by prefix. Native IDs are routed by format inference: Kalshi tickers match the all-caps-with-hyphens shape (`KX…-…`); SX Bet hashes match `0x` + 64 hex characters; numeric ids and kebab-case slugs are shared shape between Polymarket and Predict and probe Polymarket first, falling back to Predict on 404. Hyperliquid integer outcome ids collide with Polymarket/Predict numeric ids and are deliberately not inferred — route them via the composite form (`hyperliquid:<id>`) or `?platform=hyperliquid` (alias `hl`). AlphaArcade market ids are ULIDs (26-char Crockford base32, e.g. `01KQV5TQ9CE20WPEVJZX2ETNQD`); like Hyperliquid they are not inferred in v1 — route them via the composite form (`alpha-arcade:<ulid>`) or `?platform=alpha-arcade` (alias `aa`). Pass `?platform=` explicitly to skip the probe.
      *

package/dist/api/client/requests/GetMarketsRequest.d.ts

@@ -1,3 +1,4 @@
+import type * as PredictorSDK from "../../index.js";
 /**
  * @example
  *     {}
@@ -7,4 +8,6 @@ export interface GetMarketsRequest {
     limit?: number;
     /** Opaque cursor from a previous response's `pagination.nextCursor` in the SDKs (raw JSON: `pagination.next_cursor`). */
     cursor?: string;
+    /** Canonical top-level category filter. This is PredictorSDK's normalized category, not a provider-native tag. Cursors are bound to the category filter used to create them. */
+    category?: PredictorSDK.MarketCategory;
 }

package/dist/api/types/CategoriesResponse.d.ts

@@ -0,0 +1,4 @@
+import type * as PredictorSDK from "../index.js";
+export interface CategoriesResponse {
+    data: PredictorSDK.CategoryInfo[];
+}

package/dist/api/types/CategoriesResponse.js

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/api/types/CategoryInfo.d.ts

@@ -0,0 +1,8 @@
+import type * as PredictorSDK from "../index.js";
+export interface CategoryInfo {
+    id: PredictorSDK.MarketCategory;
+    /** Human-readable category label. */
+    name: string;
+    /** Short description of the category's intended scope. */
+    description: string;
+}

package/dist/api/types/CategoryInfo.js

@@ -0,0 +1,2 @@
+// This file was auto-generated by Fern from our API Definition.
+export {};

package/dist/api/types/MarketCategory.d.ts

@@ -0,0 +1,15 @@
+/** PredictorSDK-normalized top-level category. This is intentionally broad and stable across providers; provider-native tags are not exposed as canonical categories. */
+export declare const MarketCategory: {
+    readonly Sports: "sports";
+    readonly Politics: "politics";
+    readonly Crypto: "crypto";
+    readonly Finance: "finance";
+    readonly Economics: "economics";
+    readonly Weather: "weather";
+    readonly Culture: "culture";
+    readonly Technology: "technology";
+    readonly Entertainment: "entertainment";
+    readonly Other: "other";
+    readonly Unknown: "unknown";
+};
+export type MarketCategory = (typeof MarketCategory)[keyof typeof MarketCategory];

package/dist/api/types/MarketCategory.js

@@ -0,0 +1,15 @@
+// This file was auto-generated by Fern from our API Definition.
+/** PredictorSDK-normalized top-level category. This is intentionally broad and stable across providers; provider-native tags are not exposed as canonical categories. */
+export const MarketCategory = {
+    Sports: "sports",
+    Politics: "politics",
+    Crypto: "crypto",
+    Finance: "finance",
+    Economics: "economics",
+    Weather: "weather",
+    Culture: "culture",
+    Technology: "technology",
+    Entertainment: "entertainment",
+    Other: "other",
+    Unknown: "unknown",
+};

package/dist/api/types/UnifiedMarket.d.ts

@@ -6,4 +6,5 @@ export interface UnifiedMarket {
     provider: PredictorSDK.UnifiedMarketProvider;
     /** Human-readable market title/question. */
     title: string;
+    category: PredictorSDK.MarketCategory;
 }

package/dist/api/types/index.d.ts

@@ -1,3 +1,5 @@
+export * from "./CategoriesResponse.js";
+export * from "./CategoryInfo.js";
 export * from "./CryptoPriceItem.js";
 export * from "./CryptoPricesResponse.js";
 export * from "./ErrorResponse.js";
@@ -7,6 +9,7 @@ export * from "./EventResponse.js";
 export * from "./EventResponsePlatform.js";
 export * from "./GetEventRequestPlatform.js";
 export * from "./GetMarketRequestPlatform.js";
+export * from "./MarketCategory.js";
 export * from "./MarketDetailOutcome.js";
 export * from "./MarketDetailPricing.js";
 export * from "./MarketDetailPricingAvailability.js";

package/dist/api/types/index.js

@@ -1,3 +1,5 @@
+export * from "./CategoriesResponse.js";
+export * from "./CategoryInfo.js";
 export * from "./CryptoPriceItem.js";
 export * from "./CryptoPricesResponse.js";
 export * from "./ErrorResponse.js";
@@ -7,6 +9,7 @@ export * from "./EventResponse.js";
 export * from "./EventResponsePlatform.js";
 export * from "./GetEventRequestPlatform.js";
 export * from "./GetMarketRequestPlatform.js";
+export * from "./MarketCategory.js";
 export * from "./MarketDetailOutcome.js";
 export * from "./MarketDetailPricing.js";
 export * from "./MarketDetailPricingAvailability.js";

package/dist/serialization/types/CategoriesResponse.d.ts

@@ -0,0 +1,10 @@
+import type * as PredictorSDK from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { CategoryInfo } from "./CategoryInfo.js";
+export declare const CategoriesResponse: core.serialization.ObjectSchema<serializers.CategoriesResponse.Raw, PredictorSDK.CategoriesResponse>;
+export declare namespace CategoriesResponse {
+    interface Raw {
+        data: CategoryInfo.Raw[];
+    }
+}

package/dist/serialization/types/CategoriesResponse.js

@@ -0,0 +1,6 @@
+// This file was auto-generated by Fern from our API Definition.
+import * as core from "../../core/index.js";
+import { CategoryInfo } from "./CategoryInfo.js";
+export const CategoriesResponse = core.serialization.object({
+    data: core.serialization.list(CategoryInfo),
+});

package/dist/serialization/types/CategoryInfo.d.ts

@@ -0,0 +1,12 @@
+import type * as PredictorSDK from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+import { MarketCategory } from "./MarketCategory.js";
+export declare const CategoryInfo: core.serialization.ObjectSchema<serializers.CategoryInfo.Raw, PredictorSDK.CategoryInfo>;
+export declare namespace CategoryInfo {
+    interface Raw {
+        id: MarketCategory.Raw;
+        name: string;
+        description: string;
+    }
+}

package/dist/serialization/types/CategoryInfo.js

@@ -0,0 +1,8 @@
+// This file was auto-generated by Fern from our API Definition.
+import * as core from "../../core/index.js";
+import { MarketCategory } from "./MarketCategory.js";
+export const CategoryInfo = core.serialization.object({
+    id: MarketCategory,
+    name: core.serialization.string(),
+    description: core.serialization.string(),
+});

package/dist/serialization/types/MarketCategory.d.ts

@@ -0,0 +1,7 @@
+import type * as PredictorSDK from "../../api/index.js";
+import * as core from "../../core/index.js";
+import type * as serializers from "../index.js";
+export declare const MarketCategory: core.serialization.Schema<serializers.MarketCategory.Raw, PredictorSDK.MarketCategory>;
+export declare namespace MarketCategory {
+    type Raw = "sports" | "politics" | "crypto" | "finance" | "economics" | "weather" | "culture" | "technology" | "entertainment" | "other" | "unknown";
+}

package/dist/serialization/types/MarketCategory.js

@@ -0,0 +1,15 @@
+// This file was auto-generated by Fern from our API Definition.
+import * as core from "../../core/index.js";
+export const MarketCategory = core.serialization.enum_([
+    "sports",
+    "politics",
+    "crypto",
+    "finance",
+    "economics",
+    "weather",
+    "culture",
+    "technology",
+    "entertainment",
+    "other",
+    "unknown",
+]);

package/dist/serialization/types/UnifiedMarket.d.ts

@@ -1,6 +1,7 @@
 import type * as PredictorSDK from "../../api/index.js";
 import * as core from "../../core/index.js";
 import type * as serializers from "../index.js";
+import { MarketCategory } from "./MarketCategory.js";
 import { UnifiedMarketProvider } from "./UnifiedMarketProvider.js";
 export declare const UnifiedMarket: core.serialization.ObjectSchema<serializers.UnifiedMarket.Raw, PredictorSDK.UnifiedMarket>;
 export declare namespace UnifiedMarket {
@@ -8,5 +9,6 @@ export declare namespace UnifiedMarket {
         id: string;
         provider: UnifiedMarketProvider.Raw;
         title: string;
+        category: MarketCategory.Raw;
     }
 }

package/dist/serialization/types/UnifiedMarket.js

@@ -1,8 +1,10 @@
 // This file was auto-generated by Fern from our API Definition.
 import * as core from "../../core/index.js";
+import { MarketCategory } from "./MarketCategory.js";
 import { UnifiedMarketProvider } from "./UnifiedMarketProvider.js";
 export const UnifiedMarket = core.serialization.object({
     id: core.serialization.string(),
     provider: UnifiedMarketProvider,
     title: core.serialization.string(),
+    category: MarketCategory,
 });

package/dist/serialization/types/index.d.ts

@@ -1,3 +1,5 @@
+export * from "./CategoriesResponse.js";
+export * from "./CategoryInfo.js";
 export * from "./CryptoPriceItem.js";
 export * from "./CryptoPricesResponse.js";
 export * from "./ErrorResponse.js";
@@ -7,6 +9,7 @@ export * from "./EventResponse.js";
 export * from "./EventResponsePlatform.js";
 export * from "./GetEventRequestPlatform.js";
 export * from "./GetMarketRequestPlatform.js";
+export * from "./MarketCategory.js";
 export * from "./MarketDetailOutcome.js";
 export * from "./MarketDetailPricing.js";
 export * from "./MarketDetailPricingAvailability.js";

package/dist/serialization/types/index.js

@@ -1,3 +1,5 @@
+export * from "./CategoriesResponse.js";
+export * from "./CategoryInfo.js";
 export * from "./CryptoPriceItem.js";
 export * from "./CryptoPricesResponse.js";
 export * from "./ErrorResponse.js";
@@ -7,6 +9,7 @@ export * from "./EventResponse.js";
 export * from "./EventResponsePlatform.js";
 export * from "./GetEventRequestPlatform.js";
 export * from "./GetMarketRequestPlatform.js";
+export * from "./MarketCategory.js";
 export * from "./MarketDetailOutcome.js";
 export * from "./MarketDetailPricing.js";
 export * from "./MarketDetailPricingAvailability.js";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@predictorsdk/client",
-  "version": "0.8.0",
+  "version": "0.9.0",
   "description": "The official TypeScript/JavaScript client for the PredictorSDK matching markets API",
   "license": "MIT",
   "keywords": [