@saeris/tmdbkit 0.0.0 → 0.1.0

package/dist/person/types/TaggedImages.d.mts

@@ -0,0 +1,36 @@
+import { MovieMediaListItem } from "../../movie/types/MovieListItem.mjs";
+import { TvMediaListItem } from "../../tv/types/TvListItem.mjs";
+import * as v from "valibot";
+declare const _taggedImageSchema: v.ObjectSchema<{
+  readonly id: v.StringSchema<undefined>;
+  /** `backdrop`, `poster`, `still`, … */
+  readonly imageType: v.StringSchema<undefined>;
+  /** The title the image is from. */
+  readonly media: v.GenericSchema<MovieMediaListItem | TvMediaListItem>;
+  readonly mediaType: v.StringSchema<undefined>;
+  readonly aspectRatio: v.NumberSchema<undefined>;
+  readonly filePath: v.StringSchema<undefined>;
+  readonly height: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>;
+  readonly iso_3166_1: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+  readonly iso_639_1: v.NullableSchema<v.StringSchema<undefined>, undefined>;
+  readonly voteAverage: v.NumberSchema<undefined>;
+  readonly voteCount: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>;
+  readonly width: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>;
+}, undefined>;
+export interface TaggedImage extends v.InferOutput<typeof _taggedImageSchema> {}
+declare const _taggedImagesSchema: v.ObjectSchema<{
+  readonly results: v.ArraySchema<v.GenericSchema<TaggedImage>, undefined>;
+  readonly page: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>;
+  readonly totalPages: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>;
+  readonly totalResults: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>;
+  readonly id: v.SchemaWithPipe<readonly [v.NumberSchema<undefined>, v.IntegerAction<number, undefined>]>;
+}, undefined>;
+export interface TaggedImages extends v.InferOutput<typeof _taggedImagesSchema> {}
+/**
+ * ### Tagged Images
+ *
+ * A page of images from movies and TV series that a person has been tagged in (`getPersonTaggedImages`).
+ */
+export declare const taggedImagesSchema: v.GenericSchema<TaggedImages>;
+export {};
+//# sourceMappingURL=TaggedImages.d.mts.map

package/dist/person/types/TaggedImages.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaggedImages.d.mts","names":[],"sources":["../../../src/person/types/TaggedImages.ts"],"mappings":";;;cAcM,oBAAkB,EAAA;;;;;;;;;;;;;;;;iBAaP,oBAAoB,EAAE,mBAAmB;cAEpD,qBAAmB,EAAA;;;;;;;iBAMR,qBAAqB,EAAE,mBAC/B;;;;;;qBAQI,oBAAkB,EAAA,cAAA"}

package/dist/person/types/TaggedImages.mjs

@@ -0,0 +1,31 @@
+import { schema, variantSchema } from "../../validations/schema.mjs";
+import { integer } from "../../validations/integer.mjs";
+import { pageEntries } from "../../types/PagedResults.mjs";
+import { movieMediaListItemSchema } from "../../movie/types/MovieListItem.mjs";
+import { tvMediaListItemSchema } from "../../tv/types/TvListItem.mjs";
+import { imageEntries } from "../../types/Images.mjs";
+import * as v from "valibot";
+// src/person/types/TaggedImages.ts
+const _taggedImageSchema = v.object({
+	...imageEntries,
+	id: v.string(),
+	/** `backdrop`, `poster`, `still`, … */
+	imageType: v.string(),
+	/** The title the image is from. */
+	media: variantSchema(`mediaType`, [movieMediaListItemSchema, tvMediaListItemSchema]),
+	mediaType: v.string()
+});
+const _taggedImagesSchema = v.object({
+	id: integer,
+	...pageEntries,
+	results: v.array(schema(_taggedImageSchema))
+});
+/**
+* ### Tagged Images
+*
+* A page of images from movies and TV series that a person has been tagged in (`getPersonTaggedImages`).
+*/
+const taggedImagesSchema = schema(_taggedImagesSchema);
+export { taggedImagesSchema };
+
+//# sourceMappingURL=TaggedImages.mjs.map

package/dist/person/types/TaggedImages.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TaggedImages.mjs","names":[],"sources":["../../../src/person/types/TaggedImages.ts"],"sourcesContent":["import * as v from \"valibot\";\nimport { schema, variantSchema } from \"../../validations/schema.js\";\nimport { integer } from \"../../validations/integer.js\";\nimport { imageEntries } from \"../../types/Images.js\";\nimport { pageEntries } from \"../../types/PagedResults.js\";\nimport {\n  movieMediaListItemSchema,\n  type MovieMediaListItem\n} from \"../../movie/types/MovieListItem.js\";\nimport {\n  tvMediaListItemSchema,\n  type TvMediaListItem\n} from \"../../tv/types/TvListItem.js\";\n\nconst _taggedImageSchema = v.object({\n  ...imageEntries,\n  id: v.string(),\n  /** `backdrop`, `poster`, `still`, … */\n  imageType: v.string(),\n  /** The title the image is from. */\n  media: variantSchema<MovieMediaListItem | TvMediaListItem>(`mediaType`, [\n    movieMediaListItemSchema,\n    tvMediaListItemSchema\n  ]),\n  mediaType: v.string()\n});\n\nexport interface TaggedImage extends v.InferOutput<typeof _taggedImageSchema> {}\n\nconst _taggedImagesSchema = v.object({\n  id: integer,\n  ...pageEntries,\n  results: v.array(schema<TaggedImage>(_taggedImageSchema))\n});\n\nexport interface TaggedImages extends v.InferOutput<\n  typeof _taggedImagesSchema\n> {}\n\n/**\n * ### Tagged Images\n *\n * A page of images from movies and TV series that a person has been tagged in (`getPersonTaggedImages`).\n */\nexport const taggedImagesSchema = schema<TaggedImages>(_taggedImagesSchema);\n"],"mappings":";;;;;;;;AAcA,MAAM,qBAAqB,EAAE,OAAO;CAClC,GAAG;CACH,IAAI,EAAE,OAAO;;CAEb,WAAW,EAAE,OAAO;;CAEpB,OAAO,cAAoD,aAAa,CACtE,0BACA,qBACF,CAAC;CACD,WAAW,EAAE,OAAO;AACtB,CAAC;AAID,MAAM,sBAAsB,EAAE,OAAO;CACnC,IAAI;CACJ,GAAG;CACH,SAAS,EAAE,MAAM,OAAoB,kBAAkB,CAAC;AAC1D,CAAC;;;;;;AAWD,MAAa,qBAAqB,OAAqB,mBAAmB"}

package/dist/person/types/index.d.mts

@@ -0,0 +1,7 @@
+import { PersonCombinedCast, PersonCombinedCredits, PersonCombinedCrew, PersonMovieCast, PersonMovieCredits, PersonMovieCrew, PersonTvCast, PersonTvCredits, PersonTvCrew, personCombinedCreditsSchema, personMovieCreditsSchema, personTvCreditsSchema } from "./PersonCredits.mjs";
+import { PersonExternalIds, personExternalIdsSchema } from "./PersonExternalIds.mjs";
+import { TaggedImage, TaggedImages, taggedImagesSchema } from "./TaggedImages.mjs";
+import { PersonTranslationData, PersonTranslations, personTranslationsSchema } from "./PersonTranslations.mjs";
+import { PersonDetails, personAppendedEntries, personDetailsEntries, personDetailsSchema } from "./PersonDetails.mjs";
+import { PagedPersonMediaResults, PagedPersonResults, PersonListItem, PersonMediaListItem, knownFor, pagedPersonMediaResultsSchema, pagedPersonResultsSchema, personListItemEntries, personListItemSchema, personMediaListItemEntries, personMediaListItemSchema } from "./PersonListItem.mjs";
+export { PagedPersonMediaResults, PagedPersonResults, PersonCombinedCast, PersonCombinedCredits, PersonCombinedCrew, PersonDetails, PersonExternalIds, PersonListItem, PersonMediaListItem, PersonMovieCast, PersonMovieCredits, PersonMovieCrew, PersonTranslationData, PersonTranslations, PersonTvCast, PersonTvCredits, PersonTvCrew, TaggedImage, TaggedImages, knownFor, pagedPersonMediaResultsSchema, pagedPersonResultsSchema, personAppendedEntries, personCombinedCreditsSchema, personDetailsEntries, personDetailsSchema, personExternalIdsSchema, personListItemEntries, personListItemSchema, personMediaListItemEntries, personMediaListItemSchema, personMovieCreditsSchema, personTranslationsSchema, personTvCreditsSchema, taggedImagesSchema };

package/dist/person/types/index.mjs

@@ -0,0 +1,7 @@
+import { knownFor, pagedPersonMediaResultsSchema, pagedPersonResultsSchema, personListItemEntries, personListItemSchema, personMediaListItemEntries, personMediaListItemSchema } from "./PersonListItem.mjs";
+import { personCombinedCreditsSchema, personMovieCreditsSchema, personTvCreditsSchema } from "./PersonCredits.mjs";
+import { personExternalIdsSchema } from "./PersonExternalIds.mjs";
+import { personTranslationsSchema } from "./PersonTranslations.mjs";
+import { taggedImagesSchema } from "./TaggedImages.mjs";
+import { personAppendedEntries, personDetailsEntries, personDetailsSchema } from "./PersonDetails.mjs";
+export { knownFor, pagedPersonMediaResultsSchema, pagedPersonResultsSchema, personAppendedEntries, personCombinedCreditsSchema, personDetailsEntries, personDetailsSchema, personExternalIdsSchema, personListItemEntries, personListItemSchema, personMediaListItemEntries, personMediaListItemSchema, personMovieCreditsSchema, personTranslationsSchema, personTvCreditsSchema, taggedImagesSchema };

package/dist/requests/TmdbSession.d.mts

@@ -0,0 +1,91 @@
+import { RequestMethod } from "./request.mjs";
+/** Base URL for the TMDB v3 REST API. */
+export declare const endpoint: "https://api.themoviedb.org/3/";
+/**
+ * Environment variable read for the **API Read Access Token** when no token has been set explicitly. The token is sent as `Authorization: Bearer <token>` and works against both the v3 and v4 endpoints.
+ */
+export declare const TOKEN_ENV_VAR: "TMDB_API_TOKEN";
+/**
+ * Environment variable read for the legacy **v3 API key** when no bearer token is available. Sent as the `?api_key=<key>` query parameter.
+ */
+export declare const API_KEY_ENV_VAR: "TMDB_API_KEY";
+/**
+ * The API Read Access Token from the environment, or `null` when unavailable. `process` is absent on some runtimes (browsers, bare Cloudflare Workers), so the lookup is guarded rather than read directly.
+ */
+export declare const tokenFromEnv: () => string | null;
+/** The legacy v3 API key from the environment, or `null` when unavailable. */
+export declare const apiKeyFromEnv: () => string | null;
+/**
+ * The resolved credentials for a single request. A bearer token is preferred (sent as the `Authorization` header); when only a v3 API key is available it is appended to the query string instead.
+ */
+interface ResolvedAuth {
+  authorization?: string;
+  apiKey?: string;
+}
+/** A client-side rate limit: at most `requests` dispatches in any `perMs` window. */
+export interface RateLimit {
+  requests: number;
+  perMs: number;
+}
+/** What {@link TmdbSession.fetch} needs to send one request. */
+export interface SessionRequest {
+  method: RequestMethod;
+  body?: string | null;
+  signal?: AbortSignal;
+}
+/**
+ * The default client-side limit. TMDB retired its 40-requests-per-10-seconds limit on 2019-12-16; its docs now put the ceiling "somewhere in the 40 requests per second range" and warn it "could change at any time" (https://developer.themoviedb.org/docs/rate-limiting, verified 2026-10-28). Half of that leaves headroom for other clients on the same IP.
+ */
+export declare const defaultRateLimit: RateLimit;
+/**
+ * A session against the TMDB API. It holds the credentials (an API Read Access Token and/or a legacy v3 API key), keeps dispatches under a client-side {@link RateLimit}, and retries rate-limited and transient failures with backoff.
+ *
+ * Unlike discordkit's `DiscordSession`, requests are not serialised through a queue: TMDB has no per-route buckets to track, so requests run concurrently and only their _dispatch_ is spaced out. There is also no token exchange or refresh, because the API Read Access Token is used directly.
+ */
+export declare class TmdbSession {
+  #private;
+  readonly endpoint: string;
+  /** Retries after the first attempt, for `429`, `5xx` and network failures. */
+  maxRetries: number;
+  /** Base delay in ms for exponential backoff (`retryDelay * 2^attempt`), used when TMDB gives no `Retry-After`. */
+  retryDelay: number;
+  constructor(options?: {
+    token?: string;
+    apiKey?: string;
+    rateLimit?: RateLimit;
+  });
+  /**
+   * Set the **API Read Access Token** (the bare token, without a `Bearer ` prefix; it is added for you). This is the preferred credential and works against both the v3 and v4 endpoints.
+   */
+  setToken: (token: string) => this;
+  /**
+   * Set the legacy **v3 API key**. Used only when no bearer token is present, sent as the `?api_key=` query parameter.
+   */
+  setApiKey: (key: string) => this;
+  /** Replace the client-side rate limit, e.g. to go slower when sharing an IP with other TMDB clients. */
+  setRateLimit: (rateLimit: RateLimit) => this;
+  /** Clear all credentials and rate-limit state, and restore the default rate limit. */
+  clearSession: () => this;
+  /**
+   * Whether a request can authenticate right now: either a bearer token or a v3 API key is set (explicitly or via the environment).
+   */
+  get hasAuth(): boolean;
+  /**
+   * Resolve the credentials to use for a request. An explicit credential wins over the environment, and a bearer token (explicit or from the environment) wins over a v3 API key.
+   *
+   * @throws When no credential is available at all.
+   */
+  resolveAuth: () => ResolvedAuth;
+  /**
+   * Send a request: wait for a dispatch slot, attach credentials, and retry `429`, `5xx` and network failures up to {@link maxRetries} times. The final response is returned whatever its status; turning a failed response into an error is the caller's job (see `request`).
+   *
+   * Aborting `signal` rejects with its reason, whether the request is waiting for a slot, in flight, or backing off.
+   */
+  fetch: (resource: URL, init: SessionRequest) => Promise<Response>;
+  /** Requests currently waiting for a dispatch slot (useful for monitoring). */
+  getQueueSize: () => number;
+}
+/** Shared session singleton, configured once (`tmdb.setToken(…)`) and used by every operation. */
+export declare const tmdb: TmdbSession;
+export {};
+//# sourceMappingURL=TmdbSession.d.mts.map

package/dist/requests/TmdbSession.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TmdbSession.d.mts","names":[],"sources":["../../src/requests/TmdbSession.ts"],"mappings":";;qBAIa;;;;qBAKA;;;;qBAKA;;;;qBAKA;;qBAOA;;;;UASH;EACR;EACA;;;iBAIe;EACf;EACA;;;iBAIe;EACf,QAAQ;EACR;EACA,SAAS;;;;;qBAME,kBAAkB;;;;;;qBAwBlB;;WACF;;EAET;;EAEA;EAWY,YAAA;IACV;IACA;IACA,YAAY;;;;;EAUd,WAAY;;;;EAWZ,YAAa;;EASb,eAAgB,WAAW;;EAY3B;;;;MAWI;;;;;;EAcJ,mBAAkB;;;;;;EAiBlB,QAAe,UAAU,KAAK,MAAM,mBAAiB,QAAQ;;EAyC7D;;;qBA2CW,MAAM"}

package/dist/requests/TmdbSession.mjs

@@ -0,0 +1,203 @@
+import { sleep } from "../utils/sleep.mjs";
+// src/requests/TmdbSession.ts
+/** Base URL for the TMDB v3 REST API. */
+const endpoint = "https://api.themoviedb.org/3/";
+/**
+* Environment variable read for the **API Read Access Token** when no token has been set explicitly. The token is sent as `Authorization: Bearer <token>` and works against both the v3 and v4 endpoints.
+*/
+const TOKEN_ENV_VAR = "TMDB_API_TOKEN";
+/**
+* Environment variable read for the legacy **v3 API key** when no bearer token is available. Sent as the `?api_key=<key>` query parameter.
+*/
+const API_KEY_ENV_VAR = "TMDB_API_KEY";
+/**
+* The API Read Access Token from the environment, or `null` when unavailable. `process` is absent on some runtimes (browsers, bare Cloudflare Workers), so the lookup is guarded rather than read directly.
+*/
+const tokenFromEnv = () => {
+	if (typeof process === `undefined`) return null;
+	const token = process.env[TOKEN_ENV_VAR];
+	return token === void 0 || token === `` ? null : token;
+};
+/** The legacy v3 API key from the environment, or `null` when unavailable. */
+const apiKeyFromEnv = () => {
+	if (typeof process === `undefined`) return null;
+	const key = process.env[API_KEY_ENV_VAR];
+	return key === void 0 || key === `` ? null : key;
+};
+/**
+* The default client-side limit. TMDB retired its 40-requests-per-10-seconds limit on 2019-12-16; its docs now put the ceiling "somewhere in the 40 requests per second range" and warn it "could change at any time" (https://developer.themoviedb.org/docs/rate-limiting, verified 2026-10-28). Half of that leaves headroom for other clients on the same IP.
+*/
+const defaultRateLimit = {
+	requests: 20,
+	perMs: 1e3
+};
+/**
+* Responses worth retrying: rate limited, or a transient failure on TMDB's side. Everything else (`401` bad credentials, `404` unknown id, `422` bad params) fails the same way every time.
+*/
+const retryableStatuses = /* @__PURE__ */ new Set([
+	429,
+	500,
+	502,
+	503,
+	504
+]);
+/**
+* How long a `429`'s `Retry-After` asks us to wait, in ms, or `null` when absent or unparsable. TMDB doesn't document the header, so both of its HTTP forms are accepted: delta-seconds and an HTTP date.
+*/
+const retryAfterMs = (response) => {
+	const header = response.headers.get(`Retry-After`);
+	if (header === null || header.trim() === ``) return null;
+	const seconds = Number(header);
+	if (Number.isFinite(seconds)) return Math.max(0, seconds * 1e3);
+	const date = Date.parse(header);
+	return Number.isNaN(date) ? null : Math.max(0, date - Date.now());
+};
+/**
+* A session against the TMDB API. It holds the credentials (an API Read Access Token and/or a legacy v3 API key), keeps dispatches under a client-side {@link RateLimit}, and retries rate-limited and transient failures with backoff.
+*
+* Unlike discordkit's `DiscordSession`, requests are not serialised through a queue: TMDB has no per-route buckets to track, so requests run concurrently and only their _dispatch_ is spaced out. There is also no token exchange or refresh, because the API Read Access Token is used directly.
+*/
+var TmdbSession = class {
+	endpoint = endpoint;
+	/** Retries after the first attempt, for `429`, `5xx` and network failures. */
+	maxRetries = 3;
+	/** Base delay in ms for exponential backoff (`retryDelay * 2^attempt`), used when TMDB gives no `Retry-After`. */
+	retryDelay = 500;
+	#bearerToken = null;
+	#apiKey = null;
+	#rateLimit = defaultRateLimit;
+	#dispatches = [];
+	#turn = Promise.resolve();
+	#waiting = 0;
+	constructor(options) {
+		if (options?.token) this.setToken(options.token);
+		if (options?.apiKey) this.setApiKey(options.apiKey);
+		if (options?.rateLimit) this.setRateLimit(options.rateLimit);
+	}
+	/**
+	* Set the **API Read Access Token** (the bare token, without a `Bearer ` prefix; it is added for you). This is the preferred credential and works against both the v3 and v4 endpoints.
+	*/
+	setToken = (token) => {
+		if (token.length === 0) throw new Error(`Must provide a non-empty string to set the API token`);
+		this.#bearerToken = token;
+		return this;
+	};
+	/**
+	* Set the legacy **v3 API key**. Used only when no bearer token is present, sent as the `?api_key=` query parameter.
+	*/
+	setApiKey = (key) => {
+		if (key.length === 0) throw new Error(`Must provide a non-empty string to set the API key`);
+		this.#apiKey = key;
+		return this;
+	};
+	/** Replace the client-side rate limit, e.g. to go slower when sharing an IP with other TMDB clients. */
+	setRateLimit = (rateLimit) => {
+		const { requests, perMs } = rateLimit;
+		if (!Number.isInteger(requests) || requests < 1 || !(perMs > 0)) throw new Error(`A rate limit needs a whole number of requests (>= 1) per a positive number of ms, received ${requests} per ${perMs}ms`);
+		this.#rateLimit = {
+			requests,
+			perMs
+		};
+		return this;
+	};
+	/** Clear all credentials and rate-limit state, and restore the default rate limit. */
+	clearSession = () => {
+		this.#bearerToken = null;
+		this.#apiKey = null;
+		this.#rateLimit = defaultRateLimit;
+		this.#dispatches = [];
+		return this;
+	};
+	/**
+	* Whether a request can authenticate right now: either a bearer token or a v3 API key is set (explicitly or via the environment).
+	*/
+	get hasAuth() {
+		return this.#bearerToken !== null || tokenFromEnv() !== null || this.#apiKey !== null || apiKeyFromEnv() !== null;
+	}
+	/**
+	* Resolve the credentials to use for a request. An explicit credential wins over the environment, and a bearer token (explicit or from the environment) wins over a v3 API key.
+	*
+	* @throws When no credential is available at all.
+	*/
+	resolveAuth = () => {
+		const bearer = this.#bearerToken ?? tokenFromEnv();
+		if (bearer) return { authorization: `Bearer ${bearer}` };
+		const key = this.#apiKey ?? apiKeyFromEnv();
+		if (key) return { apiKey: key };
+		throw new Error(`No TMDB credentials are set, so the request cannot be authorized. Call tmdb.setToken("<API Read Access Token>"), or set ${TOKEN_ENV_VAR} (preferred) / ${API_KEY_ENV_VAR} in the environment.`);
+	};
+	/**
+	* Send a request: wait for a dispatch slot, attach credentials, and retry `429`, `5xx` and network failures up to {@link maxRetries} times. The final response is returned whatever its status; turning a failed response into an error is the caller's job (see `request`).
+	*
+	* Aborting `signal` rejects with its reason, whether the request is waiting for a slot, in flight, or backing off.
+	*/
+	fetch = async (resource, init) => {
+		for (let attempt = 0;; attempt++) {
+			await this.#acquire(init.signal);
+			const auth = this.resolveAuth();
+			const url = new URL(resource);
+			const headers = { Accept: `application/json` };
+			if (auth.authorization) headers.Authorization = auth.authorization;
+			if (auth.apiKey) url.searchParams.set(`api_key`, auth.apiKey);
+			if (init.body) headers[`Content-Type`] = `application/json`;
+			let response;
+			try {
+				response = await fetch(url, {
+					method: init.method,
+					body: init.body,
+					headers,
+					signal: init.signal
+				});
+			} catch (error) {
+				if (init.signal?.aborted || attempt >= this.maxRetries) throw error;
+				await sleep(this.retryDelay * 2 ** attempt, init.signal);
+				continue;
+			}
+			if (!retryableStatuses.has(response.status) || attempt >= this.maxRetries) return response;
+			const wait = retryAfterMs(response) ?? this.retryDelay * 2 ** attempt;
+			await response.body?.cancel();
+			await sleep(wait, init.signal);
+		}
+	};
+	/** Requests currently waiting for a dispatch slot (useful for monitoring). */
+	getQueueSize = () => this.#waiting;
+	/**
+	* Claim one dispatch slot under the rate limit. A caller whose signal aborts while waiting gives up its turn without using a slot; a later caller then moves straight on.
+	*/
+	#acquire = async (signal) => {
+		this.#waiting++;
+		const previous = this.#turn;
+		const turn = (async () => {
+			await previous;
+			await this.#claimSlot(signal);
+		})();
+		this.#turn = (async () => {
+			try {
+				await turn;
+			} catch {}
+		})();
+		try {
+			await turn;
+		} finally {
+			this.#waiting--;
+		}
+	};
+	#claimSlot = async (signal) => {
+		for (;;) {
+			signal?.throwIfAborted();
+			const now = Date.now();
+			const { requests, perMs } = this.#rateLimit;
+			this.#dispatches = this.#dispatches.filter((at) => now - at < perMs);
+			if (this.#dispatches.length < requests) {
+				this.#dispatches.push(now);
+				return;
+			}
+			await sleep(perMs - (now - this.#dispatches[0]), signal);
+		}
+	};
+};
+/** Shared session singleton, configured once (`tmdb.setToken(…)`) and used by every operation. */
+const tmdb = new TmdbSession();
+export { API_KEY_ENV_VAR, TOKEN_ENV_VAR, TmdbSession, apiKeyFromEnv, defaultRateLimit, endpoint, tmdb, tokenFromEnv };
+
+//# sourceMappingURL=TmdbSession.mjs.map

package/dist/requests/TmdbSession.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"TmdbSession.mjs","names":[],"sources":["../../src/requests/TmdbSession.ts"],"sourcesContent":["import { sleep } from \"../utils/sleep.js\";\nimport type { RequestMethod } from \"./request.js\";\n\n/** Base URL for the TMDB v3 REST API. */\nexport const endpoint = \"https://api.themoviedb.org/3/\" as const;\n\n/**\n * Environment variable read for the **API Read Access Token** when no token has been set explicitly. The token is sent as `Authorization: Bearer <token>` and works against both the v3 and v4 endpoints.\n */\nexport const TOKEN_ENV_VAR = \"TMDB_API_TOKEN\" as const;\n\n/**\n * Environment variable read for the legacy **v3 API key** when no bearer token is available. Sent as the `?api_key=<key>` query parameter.\n */\nexport const API_KEY_ENV_VAR = \"TMDB_API_KEY\" as const;\n\n/**\n * The API Read Access Token from the environment, or `null` when unavailable. `process` is absent on some runtimes (browsers, bare Cloudflare Workers), so the lookup is guarded rather than read directly.\n */\nexport const tokenFromEnv = (): string | null => {\n  if (typeof process === `undefined`) return null;\n  const token = process.env[TOKEN_ENV_VAR];\n  return token === undefined || token === `` ? null : token;\n};\n\n/** The legacy v3 API key from the environment, or `null` when unavailable. */\nexport const apiKeyFromEnv = (): string | null => {\n  if (typeof process === `undefined`) return null;\n  const key = process.env[API_KEY_ENV_VAR];\n  return key === undefined || key === `` ? null : key;\n};\n\n/**\n * The resolved credentials for a single request. A bearer token is preferred (sent as the `Authorization` header); when only a v3 API key is available it is appended to the query string instead.\n */\ninterface ResolvedAuth {\n  authorization?: string;\n  apiKey?: string;\n}\n\n/** A client-side rate limit: at most `requests` dispatches in any `perMs` window. */\nexport interface RateLimit {\n  requests: number;\n  perMs: number;\n}\n\n/** What {@link TmdbSession.fetch} needs to send one request. */\nexport interface SessionRequest {\n  method: RequestMethod;\n  body?: string | null;\n  signal?: AbortSignal;\n}\n\n/**\n * The default client-side limit. TMDB retired its 40-requests-per-10-seconds limit on 2019-12-16; its docs now put the ceiling \"somewhere in the 40 requests per second range\" and warn it \"could change at any time\" (https://developer.themoviedb.org/docs/rate-limiting, verified 2026-10-28). Half of that leaves headroom for other clients on the same IP.\n */\nexport const defaultRateLimit: RateLimit = { requests: 20, perMs: 1000 };\n\n/**\n * Responses worth retrying: rate limited, or a transient failure on TMDB's side. Everything else (`401` bad credentials, `404` unknown id, `422` bad params) fails the same way every time.\n */\nconst retryableStatuses = new Set([429, 500, 502, 503, 504]);\n\n/**\n * How long a `429`'s `Retry-After` asks us to wait, in ms, or `null` when absent or unparsable. TMDB doesn't document the header, so both of its HTTP forms are accepted: delta-seconds and an HTTP date.\n */\nconst retryAfterMs = (response: Response): number | null => {\n  const header = response.headers.get(`Retry-After`);\n  if (header === null || header.trim() === ``) return null;\n  const seconds = Number(header);\n  if (Number.isFinite(seconds)) return Math.max(0, seconds * 1000);\n  const date = Date.parse(header);\n  return Number.isNaN(date) ? null : Math.max(0, date - Date.now());\n};\n\n/**\n * A session against the TMDB API. It holds the credentials (an API Read Access Token and/or a legacy v3 API key), keeps dispatches under a client-side {@link RateLimit}, and retries rate-limited and transient failures with backoff.\n *\n * Unlike discordkit's `DiscordSession`, requests are not serialised through a queue: TMDB has no per-route buckets to track, so requests run concurrently and only their _dispatch_ is spaced out. There is also no token exchange or refresh, because the API Read Access Token is used directly.\n */\nexport class TmdbSession {\n  readonly endpoint: string = endpoint;\n  /** Retries after the first attempt, for `429`, `5xx` and network failures. */\n  maxRetries: number = 3;\n  /** Base delay in ms for exponential backoff (`retryDelay * 2^attempt`), used when TMDB gives no `Retry-After`. */\n  retryDelay: number = 500;\n\n  #bearerToken: string | null = null;\n  #apiKey: string | null = null;\n\n  #rateLimit: RateLimit = defaultRateLimit;\n  #dispatches: number[] = [];\n  // Callers take turns claiming a dispatch slot, so two concurrent callers can't both see the same free slot. Only the claiming is sequential; the fetches overlap.\n  #turn: Promise<void> = Promise.resolve();\n  #waiting = 0;\n\n  constructor(options?: {\n    token?: string;\n    apiKey?: string;\n    rateLimit?: RateLimit;\n  }) {\n    if (options?.token) this.setToken(options.token);\n    if (options?.apiKey) this.setApiKey(options.apiKey);\n    if (options?.rateLimit) this.setRateLimit(options.rateLimit);\n  }\n\n  /**\n   * Set the **API Read Access Token** (the bare token, without a `Bearer ` prefix; it is added for you). This is the preferred credential and works against both the v3 and v4 endpoints.\n   */\n  setToken = (token: string): this => {\n    if (token.length === 0) {\n      throw new Error(`Must provide a non-empty string to set the API token`);\n    }\n    this.#bearerToken = token;\n    return this;\n  };\n\n  /**\n   * Set the legacy **v3 API key**. Used only when no bearer token is present, sent as the `?api_key=` query parameter.\n   */\n  setApiKey = (key: string): this => {\n    if (key.length === 0) {\n      throw new Error(`Must provide a non-empty string to set the API key`);\n    }\n    this.#apiKey = key;\n    return this;\n  };\n\n  /** Replace the client-side rate limit, e.g. to go slower when sharing an IP with other TMDB clients. */\n  setRateLimit = (rateLimit: RateLimit): this => {\n    const { requests, perMs } = rateLimit;\n    if (!Number.isInteger(requests) || requests < 1 || !(perMs > 0)) {\n      throw new Error(\n        `A rate limit needs a whole number of requests (>= 1) per a positive number of ms, received ${requests} per ${perMs}ms`\n      );\n    }\n    this.#rateLimit = { requests, perMs };\n    return this;\n  };\n\n  /** Clear all credentials and rate-limit state, and restore the default rate limit. */\n  clearSession = (): this => {\n    this.#bearerToken = null;\n    this.#apiKey = null;\n    this.#rateLimit = defaultRateLimit;\n    this.#dispatches = [];\n    return this;\n  };\n\n  /**\n   * Whether a request can authenticate right now: either a bearer token or a v3 API key is set (explicitly or via the environment).\n   */\n  get hasAuth(): boolean {\n    return (\n      this.#bearerToken !== null ||\n      tokenFromEnv() !== null ||\n      this.#apiKey !== null ||\n      apiKeyFromEnv() !== null\n    );\n  }\n\n  /**\n   * Resolve the credentials to use for a request. An explicit credential wins over the environment, and a bearer token (explicit or from the environment) wins over a v3 API key.\n   *\n   * @throws When no credential is available at all.\n   */\n  resolveAuth = (): ResolvedAuth => {\n    const bearer = this.#bearerToken ?? tokenFromEnv();\n    if (bearer) return { authorization: `Bearer ${bearer}` };\n\n    const key = this.#apiKey ?? apiKeyFromEnv();\n    if (key) return { apiKey: key };\n\n    throw new Error(\n      `No TMDB credentials are set, so the request cannot be authorized. Call tmdb.setToken(\"<API Read Access Token>\"), or set ${TOKEN_ENV_VAR} (preferred) / ${API_KEY_ENV_VAR} in the environment.`\n    );\n  };\n\n  /**\n   * Send a request: wait for a dispatch slot, attach credentials, and retry `429`, `5xx` and network failures up to {@link maxRetries} times. The final response is returned whatever its status; turning a failed response into an error is the caller's job (see `request`).\n   *\n   * Aborting `signal` rejects with its reason, whether the request is waiting for a slot, in flight, or backing off.\n   */\n  fetch = async (resource: URL, init: SessionRequest): Promise<Response> => {\n    for (let attempt = 0; ; attempt++) {\n      await this.#acquire(init.signal);\n\n      const auth = this.resolveAuth();\n      const url = new URL(resource);\n      const headers: Record<string, string> = { Accept: `application/json` };\n      if (auth.authorization) headers.Authorization = auth.authorization;\n      if (auth.apiKey) url.searchParams.set(`api_key`, auth.apiKey);\n      if (init.body) headers[`Content-Type`] = `application/json`;\n\n      let response: Response;\n      try {\n        response = await fetch(url, {\n          method: init.method,\n          body: init.body,\n          headers,\n          signal: init.signal\n        });\n      } catch (error) {\n        // An abort is the caller's decision, not a transient failure.\n        if (init.signal?.aborted || attempt >= this.maxRetries) throw error;\n        await sleep(this.retryDelay * 2 ** attempt, init.signal);\n        continue;\n      }\n\n      if (\n        !retryableStatuses.has(response.status) ||\n        attempt >= this.maxRetries\n      ) {\n        return response;\n      }\n\n      const wait = retryAfterMs(response) ?? this.retryDelay * 2 ** attempt;\n      // Release the connection held by the unread body before waiting.\n      await response.body?.cancel();\n      await sleep(wait, init.signal);\n    }\n  };\n\n  /** Requests currently waiting for a dispatch slot (useful for monitoring). */\n  getQueueSize = (): number => this.#waiting;\n\n  /**\n   * Claim one dispatch slot under the rate limit. A caller whose signal aborts while waiting gives up its turn without using a slot; a later caller then moves straight on.\n   */\n  #acquire = async (signal?: AbortSignal): Promise<void> => {\n    this.#waiting++;\n    const previous = this.#turn;\n    const turn = (async (): Promise<void> => {\n      await previous;\n      await this.#claimSlot(signal);\n    })();\n    // The next caller waits on this turn settling, never on it succeeding: an aborted turn must not stall the callers behind it. The abort itself reaches this caller through `await turn` below.\n    this.#turn = (async (): Promise<void> => {\n      try {\n        await turn;\n      } catch {\n        // handled by the caller that owns the turn\n      }\n    })();\n    try {\n      await turn;\n    } finally {\n      this.#waiting--;\n    }\n  };\n\n  #claimSlot = async (signal?: AbortSignal): Promise<void> => {\n    for (;;) {\n      signal?.throwIfAborted();\n      const now = Date.now();\n      const { requests, perMs } = this.#rateLimit;\n      this.#dispatches = this.#dispatches.filter((at) => now - at < perMs);\n      if (this.#dispatches.length < requests) {\n        this.#dispatches.push(now);\n        return;\n      }\n      await sleep(perMs - (now - this.#dispatches[0]), signal);\n    }\n  };\n}\n\n/** Shared session singleton, configured once (`tmdb.setToken(…)`) and used by every operation. */\nexport const tmdb: TmdbSession = new TmdbSession();\n"],"mappings":";;;AAIA,MAAa,WAAW;;;;AAKxB,MAAa,gBAAgB;;;;AAK7B,MAAa,kBAAkB;;;;AAK/B,MAAa,qBAAoC;CAC/C,IAAI,OAAO,YAAY,aAAa,OAAO;CAC3C,MAAM,QAAQ,QAAQ,IAAI;CAC1B,OAAO,UAAU,KAAA,KAAa,UAAU,KAAK,OAAO;AACtD;;AAGA,MAAa,sBAAqC;CAChD,IAAI,OAAO,YAAY,aAAa,OAAO;CAC3C,MAAM,MAAM,QAAQ,IAAI;CACxB,OAAO,QAAQ,KAAA,KAAa,QAAQ,KAAK,OAAO;AAClD;;;;AA0BA,MAAa,mBAA8B;CAAE,UAAU;CAAI,OAAO;AAAK;;;;AAKvE,MAAM,oCAAoB,IAAI,IAAI;CAAC;CAAK;CAAK;CAAK;CAAK;AAAG,CAAC;;;;AAK3D,MAAM,gBAAgB,aAAsC;CAC1D,MAAM,SAAS,SAAS,QAAQ,IAAI,aAAa;CACjD,IAAI,WAAW,QAAQ,OAAO,KAAK,MAAM,IAAI,OAAO;CACpD,MAAM,UAAU,OAAO,MAAM;CAC7B,IAAI,OAAO,SAAS,OAAO,GAAG,OAAO,KAAK,IAAI,GAAG,UAAU,GAAI;CAC/D,MAAM,OAAO,KAAK,MAAM,MAAM;CAC9B,OAAO,OAAO,MAAM,IAAI,IAAI,OAAO,KAAK,IAAI,GAAG,OAAO,KAAK,IAAI,CAAC;AAClE;;;;;;AAOA,IAAa,cAAb,MAAyB;CACvB,WAA4B;;CAE5B,aAAqB;;CAErB,aAAqB;CAErB,eAA8B;CAC9B,UAAyB;CAEzB,aAAwB;CACxB,cAAwB,CAAC;CAEzB,QAAuB,QAAQ,QAAQ;CACvC,WAAW;CAEX,YAAY,SAIT;EACD,IAAI,SAAS,OAAO,KAAK,SAAS,QAAQ,KAAK;EAC/C,IAAI,SAAS,QAAQ,KAAK,UAAU,QAAQ,MAAM;EAClD,IAAI,SAAS,WAAW,KAAK,aAAa,QAAQ,SAAS;CAC7D;;;;CAKA,YAAY,UAAwB;EAClC,IAAI,MAAM,WAAW,GACnB,MAAM,IAAI,MAAM,sDAAsD;EAExE,KAAK,eAAe;EACpB,OAAO;CACT;;;;CAKA,aAAa,QAAsB;EACjC,IAAI,IAAI,WAAW,GACjB,MAAM,IAAI,MAAM,oDAAoD;EAEtE,KAAK,UAAU;EACf,OAAO;CACT;;CAGA,gBAAgB,cAA+B;EAC7C,MAAM,EAAE,UAAU,UAAU;EAC5B,IAAI,CAAC,OAAO,UAAU,QAAQ,KAAK,WAAW,KAAK,EAAE,QAAQ,IAC3D,MAAM,IAAI,MACR,8FAA8F,SAAS,OAAO,MAAM,GACtH;EAEF,KAAK,aAAa;GAAE;GAAU;EAAM;EACpC,OAAO;CACT;;CAGA,qBAA2B;EACzB,KAAK,eAAe;EACpB,KAAK,UAAU;EACf,KAAK,aAAa;EAClB,KAAK,cAAc,CAAC;EACpB,OAAO;CACT;;;;CAKA,IAAI,UAAmB;EACrB,OACE,KAAK,iBAAiB,QACtB,aAAa,MAAM,QACnB,KAAK,YAAY,QACjB,cAAc,MAAM;CAExB;;;;;;CAOA,oBAAkC;EAChC,MAAM,SAAS,KAAK,gBAAgB,aAAa;EACjD,IAAI,QAAQ,OAAO,EAAE,eAAe,UAAU,SAAS;EAEvD,MAAM,MAAM,KAAK,WAAW,cAAc;EAC1C,IAAI,KAAK,OAAO,EAAE,QAAQ,IAAI;EAE9B,MAAM,IAAI,MACR,2HAA2H,cAAc,iBAAiB,gBAAgB,qBAC5K;CACF;;;;;;CAOA,QAAQ,OAAO,UAAe,SAA4C;EACxE,KAAK,IAAI,UAAU,IAAK,WAAW;GACjC,MAAM,KAAK,SAAS,KAAK,MAAM;GAE/B,MAAM,OAAO,KAAK,YAAY;GAC9B,MAAM,MAAM,IAAI,IAAI,QAAQ;GAC5B,MAAM,UAAkC,EAAE,QAAQ,mBAAmB;GACrE,IAAI,KAAK,eAAe,QAAQ,gBAAgB,KAAK;GACrD,IAAI,KAAK,QAAQ,IAAI,aAAa,IAAI,WAAW,KAAK,MAAM;GAC5D,IAAI,KAAK,MAAM,QAAQ,kBAAkB;GAEzC,IAAI;GACJ,IAAI;IACF,WAAW,MAAM,MAAM,KAAK;KAC1B,QAAQ,KAAK;KACb,MAAM,KAAK;KACX;KACA,QAAQ,KAAK;IACf,CAAC;GACH,SAAS,OAAO;IAEd,IAAI,KAAK,QAAQ,WAAW,WAAW,KAAK,YAAY,MAAM;IAC9D,MAAM,MAAM,KAAK,aAAa,KAAK,SAAS,KAAK,MAAM;IACvD;GACF;GAEA,IACE,CAAC,kBAAkB,IAAI,SAAS,MAAM,KACtC,WAAW,KAAK,YAEhB,OAAO;GAGT,MAAM,OAAO,aAAa,QAAQ,KAAK,KAAK,aAAa,KAAK;GAE9D,MAAM,SAAS,MAAM,OAAO;GAC5B,MAAM,MAAM,MAAM,KAAK,MAAM;EAC/B;CACF;;CAGA,qBAA6B,KAAK;;;;CAKlC,WAAW,OAAO,WAAwC;EACxD,KAAK;EACL,MAAM,WAAW,KAAK;EACtB,MAAM,QAAQ,YAA2B;GACvC,MAAM;GACN,MAAM,KAAK,WAAW,MAAM;EAC9B,EAAA,CAAG;EAEH,KAAK,SAAS,YAA2B;GACvC,IAAI;IACF,MAAM;GACR,QAAQ,CAER;EACF,EAAA,CAAG;EACH,IAAI;GACF,MAAM;EACR,UAAU;GACR,KAAK;EACP;CACF;CAEA,aAAa,OAAO,WAAwC;EAC1D,SAAS;GACP,QAAQ,eAAe;GACvB,MAAM,MAAM,KAAK,IAAI;GACrB,MAAM,EAAE,UAAU,UAAU,KAAK;GACjC,KAAK,cAAc,KAAK,YAAY,QAAQ,OAAO,MAAM,KAAK,KAAK;GACnE,IAAI,KAAK,YAAY,SAAS,UAAU;IACtC,KAAK,YAAY,KAAK,GAAG;IACzB;GACF;GACA,MAAM,MAAM,SAAS,MAAM,KAAK,YAAY,KAAK,MAAM;EACzD;CACF;AACF;;AAGA,MAAa,OAAoB,IAAI,YAAY"}

package/dist/requests/addParams.d.mts

@@ -0,0 +1,15 @@
+type ParamValue = Array<number | string> | boolean | number | string | null | undefined;
+/**
+ * The shape of query params accepted by the typed helpers. `null`/`undefined` values are skipped. A nested object is a range: `{ voteAverage: { gte: 7, lte: 9 } }`.
+ */
+export type RequestParams = Partial<Record<string, ParamValue | Partial<Record<string, ParamValue>>>>;
+/**
+ * Append query params to a URL. Keys are converted from camelCase to snake_case (TMDB's wire format).
+ *
+ * Arrays are **comma-joined**, never repeated: TMDB reads lists as one comma-separated value (`append_to_response=credits,images`, `with_genres=28,12` meaning AND). For OR-logic TMDB uses `|`, which callers pass as a single string (`with_genres: "28|12"`).
+ *
+ * Nested objects become TMDB's dotted range params, the way the old tmdb-api's `buildNumberRange`/`buildDateRange` did: `{ primaryReleaseDate: { gte: "2020-01-01" } }` → `primary_release_date.gte=2020-01-01`.
+ */
+export declare const addParams: (url: URL, params: RequestParams) => URL;
+export {};
+//# sourceMappingURL=addParams.d.mts.map

package/dist/requests/addParams.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"addParams.d.mts","names":[],"sources":["../../src/requests/addParams.ts"],"mappings":"A,KAEK,aACD;;;;YAUQ,gBAAgB,QAC1B,eAAe,aAAa,QAAQ,eAAe;;;;;;;;qBAaxC,YAAa,KAAK,KAAK,QAAQ,kBAAgB"}

package/dist/requests/addParams.mjs

@@ -0,0 +1,27 @@
+import { toSnakeCase } from "../utils/toSnakeCase.mjs";
+// src/requests/addParams.ts
+const serialize = (value) => Array.isArray(value) ? value.join(`,`) : String(value);
+/**
+* Append query params to a URL. Keys are converted from camelCase to snake_case (TMDB's wire format).
+*
+* Arrays are **comma-joined**, never repeated: TMDB reads lists as one comma-separated value (`append_to_response=credits,images`, `with_genres=28,12` meaning AND). For OR-logic TMDB uses `|`, which callers pass as a single string (`with_genres: "28|12"`).
+*
+* Nested objects become TMDB's dotted range params, the way the old tmdb-api's `buildNumberRange`/`buildDateRange` did: `{ primaryReleaseDate: { gte: "2020-01-01" } }` → `primary_release_date.gte=2020-01-01`.
+*/
+const addParams = (url, params) => {
+	for (const [key, value] of Object.entries(params)) {
+		if (value === null || value === void 0) continue;
+		if (typeof value === `object` && !Array.isArray(value)) {
+			for (const [bound, limit] of Object.entries(value)) {
+				if (limit === null || limit === void 0) continue;
+				url.searchParams.set(`${toSnakeCase(key)}.${bound}`, serialize(limit));
+			}
+			continue;
+		}
+		url.searchParams.set(toSnakeCase(key), serialize(value));
+	}
+	return url;
+};
+export { addParams };
+
+//# sourceMappingURL=addParams.mjs.map

package/dist/requests/addParams.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"addParams.mjs","names":[],"sources":["../../src/requests/addParams.ts"],"sourcesContent":["import { toSnakeCase } from \"../utils/toSnakeCase.js\";\n\ntype ParamValue =\n  | Array<number | string>\n  | boolean\n  | number\n  | string\n  | null\n  | undefined;\n\n/**\n * The shape of query params accepted by the typed helpers. `null`/`undefined` values are skipped. A nested object is a range: `{ voteAverage: { gte: 7, lte: 9 } }`.\n */\nexport type RequestParams = Partial<\n  Record<string, ParamValue | Partial<Record<string, ParamValue>>>\n>;\n\nconst serialize = (value: Exclude<ParamValue, null | undefined>): string =>\n  Array.isArray(value) ? value.join(`,`) : String(value);\n\n/**\n * Append query params to a URL. Keys are converted from camelCase to snake_case (TMDB's wire format).\n *\n * Arrays are **comma-joined**, never repeated: TMDB reads lists as one comma-separated value (`append_to_response=credits,images`, `with_genres=28,12` meaning AND). For OR-logic TMDB uses `|`, which callers pass as a single string (`with_genres: \"28|12\"`).\n *\n * Nested objects become TMDB's dotted range params, the way the old tmdb-api's `buildNumberRange`/`buildDateRange` did: `{ primaryReleaseDate: { gte: \"2020-01-01\" } }` → `primary_release_date.gte=2020-01-01`.\n */\nexport const addParams = (url: URL, params: RequestParams): URL => {\n  for (const [key, value] of Object.entries(params)) {\n    if (value === null || value === undefined) continue;\n    if (typeof value === `object` && !Array.isArray(value)) {\n      for (const [bound, limit] of Object.entries(value)) {\n        if (limit === null || limit === undefined) continue;\n        url.searchParams.set(`${toSnakeCase(key)}.${bound}`, serialize(limit));\n      }\n      continue;\n    }\n    url.searchParams.set(toSnakeCase(key), serialize(value));\n  }\n  return url;\n};\n"],"mappings":";;AAiBA,MAAM,aAAa,UACjB,MAAM,QAAQ,KAAK,IAAI,MAAM,KAAK,GAAG,IAAI,OAAO,KAAK;;;;;;;;AASvD,MAAa,aAAa,KAAU,WAA+B;CACjE,KAAK,MAAM,CAAC,KAAK,UAAU,OAAO,QAAQ,MAAM,GAAG;EACjD,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW;EAC3C,IAAI,OAAO,UAAU,YAAY,CAAC,MAAM,QAAQ,KAAK,GAAG;GACtD,KAAK,MAAM,CAAC,OAAO,UAAU,OAAO,QAAQ,KAAK,GAAG;IAClD,IAAI,UAAU,QAAQ,UAAU,KAAA,GAAW;IAC3C,IAAI,aAAa,IAAI,GAAG,YAAY,GAAG,EAAE,GAAG,SAAS,UAAU,KAAK,CAAC;GACvE;GACA;EACF;EACA,IAAI,aAAa,IAAI,YAAY,GAAG,GAAG,UAAU,KAAK,CAAC;CACzD;CACA,OAAO;AACT"}

package/dist/requests/buildURL.d.mts

@@ -0,0 +1,11 @@
+import { RequestParams } from "./addParams.mjs";
+/**
+ * Build a full URL against the TMDB endpoint, appending query params.
+ *
+ * @param resource - The path, e.g. `/search/movie` or `search/movie`.
+ * @param params - Optional query params (camelCase keys are converted to snake_case).
+ *
+ * @__NO_SIDE_EFFECTS__
+ */
+export declare const buildURL: (resource: string, params?: RequestParams) => URL;
+//# sourceMappingURL=buildURL.d.mts.map

package/dist/requests/buildURL.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildURL.d.mts","names":[],"sources":["../../src/requests/buildURL.ts"],"mappings":";;;;;;;;;qBAYa,WAAY,kBAAkB,SAAS,kBAAgB"}

package/dist/requests/buildURL.mjs

@@ -0,0 +1,15 @@
+import { addParams } from "./addParams.mjs";
+import { endpoint } from "./TmdbSession.mjs";
+// src/requests/buildURL.ts
+/**
+* Build a full URL against the TMDB endpoint, appending query params.
+*
+* @param resource - The path, e.g. `/search/movie` or `search/movie`.
+* @param params - Optional query params (camelCase keys are converted to snake_case).
+*
+* @__NO_SIDE_EFFECTS__
+*/
+const buildURL = (resource, params) => addParams(new URL(resource.replace(/^\//, ``), endpoint), params ?? {});
+export { buildURL };
+
+//# sourceMappingURL=buildURL.mjs.map

package/dist/requests/buildURL.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"buildURL.mjs","names":[],"sources":["../../src/requests/buildURL.ts"],"sourcesContent":["import { addParams } from \"./addParams.js\";\nimport { endpoint } from \"./TmdbSession.js\";\nimport type { RequestParams } from \"./addParams.js\";\n\n/**\n * Build a full URL against the TMDB endpoint, appending query params.\n *\n * @param resource - The path, e.g. `/search/movie` or `search/movie`.\n * @param params - Optional query params (camelCase keys are converted to snake_case).\n *\n * @__NO_SIDE_EFFECTS__\n */\nexport const buildURL = (resource: string, params?: RequestParams): URL =>\n  addParams(new URL(resource.replace(/^\\//, ``), endpoint), params ?? {});\n"],"mappings":";;;;;;;;;;;AAYA,MAAa,YAAY,UAAkB,WACzC,UAAU,IAAI,IAAI,SAAS,QAAQ,OAAO,EAAE,GAAG,QAAQ,GAAG,UAAU,CAAC,CAAC"}

package/dist/requests/index.d.mts

@@ -0,0 +1,7 @@
+import { RequestBody, RequestMethod, RequestOptions, TmdbApiError, request } from "./request.mjs";
+import { RequestParams, addParams } from "./addParams.mjs";
+import { Fetcher, get, patch, post, put, remove } from "./methods.mjs";
+import { API_KEY_ENV_VAR, RateLimit, SessionRequest, TOKEN_ENV_VAR, TmdbSession, apiKeyFromEnv, defaultRateLimit, endpoint, tmdb, tokenFromEnv } from "./TmdbSession.mjs";
+import { toValidated } from "./toValidated.mjs";
+import { buildURL } from "./buildURL.mjs";
+export { API_KEY_ENV_VAR, type Fetcher, type RateLimit, type RequestBody, type RequestMethod, type RequestOptions, type RequestParams, type SessionRequest, TOKEN_ENV_VAR, TmdbApiError, TmdbSession, addParams, apiKeyFromEnv, buildURL, defaultRateLimit, endpoint, get, patch, post, put, remove, request, tmdb, toValidated, tokenFromEnv };

package/dist/requests/index.mjs

@@ -0,0 +1,7 @@
+import { addParams } from "./addParams.mjs";
+import { API_KEY_ENV_VAR, TOKEN_ENV_VAR, TmdbSession, apiKeyFromEnv, defaultRateLimit, endpoint, tmdb, tokenFromEnv } from "./TmdbSession.mjs";
+import { buildURL } from "./buildURL.mjs";
+import { TmdbApiError, request } from "./request.mjs";
+import { get, patch, post, put, remove } from "./methods.mjs";
+import { toValidated } from "./toValidated.mjs";
+export { API_KEY_ENV_VAR, TOKEN_ENV_VAR, TmdbApiError, TmdbSession, addParams, apiKeyFromEnv, buildURL, defaultRateLimit, endpoint, get, patch, post, put, remove, request, tmdb, toValidated, tokenFromEnv };

package/dist/requests/methods.d.mts

@@ -0,0 +1,22 @@
+import { RequestBody, RequestOptions } from "./request.mjs";
+import { RequestParams } from "./addParams.mjs";
+import { GenericSchema, GenericSchemaAsync, InferOutput } from "valibot";
+/**
+ * A typed fetcher. When the input schema is `null` the fetcher takes only the per-call {@link RequestOptions}; otherwise it takes the schema's output as its first argument and the options second.
+ */
+export type Fetcher<
+/** A schema to validate the input arguments of a fetch call */
+S extends GenericSchema | GenericSchemaAsync | null = null,
+/** The return value expected from the fetch call */
+R = void> = S extends null ? (options?: RequestOptions) => Promise<R> : (config: InferOutput<NonNullable<S>>, options?: RequestOptions) => Promise<R>;
+/** Perform a `GET` request to the given resource, with optional query params. */
+export declare const get: <T = void>(url: string, params?: RequestParams, options?: RequestOptions) => Promise<T>;
+/** Perform a `POST` request to the given resource with an optional body. */
+export declare const post: <T = void>(url: string, body?: RequestBody, options?: RequestOptions) => Promise<T>;
+/** Perform a `PUT` request to the given resource with an optional body. */
+export declare const put: <T = void>(url: string, body?: RequestBody, options?: RequestOptions) => Promise<T>;
+/** Perform a `PATCH` request to the given resource with an optional body. */
+export declare const patch: <T = void>(url: string, body?: RequestBody, options?: RequestOptions) => Promise<T>;
+/** Perform a `DELETE` request to the given resource. */
+export declare const remove: <T = void>(url: string, options?: RequestOptions) => Promise<T>;
+//# sourceMappingURL=methods.d.mts.map

package/dist/requests/methods.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.d.mts","names":[],"sources":["../../src/requests/methods.ts"],"mappings":";;;;;;YASY;;AAEV,UAAU,gBAAgB;;AAE1B,YACE,kBACC,UAAU,mBAAmB,QAAQ,MAEpC,QAAQ,YAAY,YAAY,KAChC,UAAU,mBACP,QAAQ;;qBAGJ,MAAa,UACxB,aACA,SAAS,eACT,UAAU,mBACT,QAAQ;;qBAGE,OAAc,UACzB,aACA,OAAO,aACP,UAAU,mBACT,QAAQ;;qBAGE,MAAa,UACxB,aACA,OAAO,aACP,UAAU,mBACT,QAAQ;;qBAGE,QAAe,UAC1B,aACA,OAAO,aACP,UAAU,mBACT,QAAQ;;qBAGE,SAAgB,UAC3B,aACA,UAAU,mBACT,QAAQ"}

package/dist/requests/methods.mjs

@@ -0,0 +1,16 @@
+import { buildURL } from "./buildURL.mjs";
+import { request } from "./request.mjs";
+// src/requests/methods.ts
+/** Perform a `GET` request to the given resource, with optional query params. */
+const get = async (url, params, options) => request(buildURL(url, params), `GET`, void 0, options);
+/** Perform a `POST` request to the given resource with an optional body. */
+const post = async (url, body, options) => request(buildURL(url), `POST`, body, options);
+/** Perform a `PUT` request to the given resource with an optional body. */
+const put = async (url, body, options) => request(buildURL(url), `PUT`, body, options);
+/** Perform a `PATCH` request to the given resource with an optional body. */
+const patch = async (url, body, options) => request(buildURL(url), `PATCH`, body, options);
+/** Perform a `DELETE` request to the given resource. */
+const remove = async (url, options) => request(buildURL(url), `DELETE`, void 0, options);
+export { get, patch, post, put, remove };
+
+//# sourceMappingURL=methods.mjs.map

package/dist/requests/methods.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"methods.mjs","names":[],"sources":["../../src/requests/methods.ts"],"sourcesContent":["import type { GenericSchema, GenericSchemaAsync, InferOutput } from \"valibot\";\nimport { buildURL } from \"./buildURL.js\";\nimport { request } from \"./request.js\";\nimport type { RequestBody, RequestOptions } from \"./request.js\";\nimport type { RequestParams } from \"./addParams.js\";\n\n/**\n * A typed fetcher. When the input schema is `null` the fetcher takes only the per-call {@link RequestOptions}; otherwise it takes the schema's output as its first argument and the options second.\n */\nexport type Fetcher<\n  /** A schema to validate the input arguments of a fetch call */\n  S extends GenericSchema | GenericSchemaAsync | null = null,\n  /** The return value expected from the fetch call */\n  R = void\n> = S extends null\n  ? (options?: RequestOptions) => Promise<R>\n  : (\n      config: InferOutput<NonNullable<S>>,\n      options?: RequestOptions\n    ) => Promise<R>;\n\n/** Perform a `GET` request to the given resource, with optional query params. */\nexport const get = async <T = void>(\n  url: string,\n  params?: RequestParams,\n  options?: RequestOptions\n): Promise<T> => request(buildURL(url, params), `GET`, undefined, options);\n\n/** Perform a `POST` request to the given resource with an optional body. */\nexport const post = async <T = void>(\n  url: string,\n  body?: RequestBody,\n  options?: RequestOptions\n): Promise<T> => request(buildURL(url), `POST`, body, options);\n\n/** Perform a `PUT` request to the given resource with an optional body. */\nexport const put = async <T = void>(\n  url: string,\n  body?: RequestBody,\n  options?: RequestOptions\n): Promise<T> => request(buildURL(url), `PUT`, body, options);\n\n/** Perform a `PATCH` request to the given resource with an optional body. */\nexport const patch = async <T = void>(\n  url: string,\n  body?: RequestBody,\n  options?: RequestOptions\n): Promise<T> => request(buildURL(url), `PATCH`, body, options);\n\n/** Perform a `DELETE` request to the given resource. */\nexport const remove = async <T = void>(\n  url: string,\n  options?: RequestOptions\n): Promise<T> => request(buildURL(url), `DELETE`, undefined, options);\n"],"mappings":";;;;AAsBA,MAAa,MAAM,OACjB,KACA,QACA,YACe,QAAQ,SAAS,KAAK,MAAM,GAAG,OAAO,KAAA,GAAW,OAAO;;AAGzE,MAAa,OAAO,OAClB,KACA,MACA,YACe,QAAQ,SAAS,GAAG,GAAG,QAAQ,MAAM,OAAO;;AAG7D,MAAa,MAAM,OACjB,KACA,MACA,YACe,QAAQ,SAAS,GAAG,GAAG,OAAO,MAAM,OAAO;;AAG5D,MAAa,QAAQ,OACnB,KACA,MACA,YACe,QAAQ,SAAS,GAAG,GAAG,SAAS,MAAM,OAAO;;AAG9D,MAAa,SAAS,OACpB,KACA,YACe,QAAQ,SAAS,GAAG,GAAG,UAAU,KAAA,GAAW,OAAO"}

package/dist/requests/request.d.mts

@@ -0,0 +1,28 @@
+export type RequestBody = object | null | undefined;
+/**
+ * The HTTP methods the TMDB REST API uses, and the only ones the typed helpers in `methods.ts` emit. Most of TMDB is read-only `GET`; the account, list, rating and session endpoints also `POST` and `DELETE`.
+ */
+export type RequestMethod = `GET` | `POST` | `PUT` | `PATCH` | `DELETE`;
+/**
+ * Per-call options a {@link Fetcher} accepts as its last argument and forwards to the request layer.
+ */
+export interface RequestOptions {
+  /** Abort the request: while it waits for a rate-limit slot, while it is in flight, or while it backs off before a retry. */
+  signal?: AbortSignal;
+}
+/**
+ * A structured error thrown when the TMDB API responds with a non-2xx status. TMDB reports failures as `{ status_code, status_message }` in the body; `statusCode` is `0` when the body didn't carry one.
+ *
+ * The message names the method and path but never the query string, which can hold a v3 `api_key`.
+ */
+export declare class TmdbApiError extends Error {
+  readonly status: number;
+  readonly statusCode: number;
+  readonly statusMessage: string;
+  constructor(status: number, statusCode: number, statusMessage: string, request?: {
+    method: RequestMethod;
+    path: string;
+  });
+}
+export declare const request: <T>(resource: URL, method?: RequestMethod, body?: RequestBody, options?: RequestOptions) => Promise<T>;
+//# sourceMappingURL=request.d.mts.map

package/dist/requests/request.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"request.d.mts","names":[],"sources":["../../src/requests/request.ts"],"mappings":"A,YAKY;;;;YAKA;;;;iBAKK;;EAEf,SAAS;;;;;;;qBAQE,qBAAqB;WACvB;WACA;WACA;EAGP,YAAA,gBACA,oBACA,uBACA;IAAY,QAAQ;IAAe;;;qBAW1B,UAAiB,GAC5B,UAAU,KACV,SAAQ,eACR,OAAO,aACP,UAAU,mBACT,QAAQ"}