@omelhorsite/sdk 0.2.0 → 0.4.0

package/dist/types/resources/movies/collections.d.ts

@@ -0,0 +1,352 @@
+/** The `movies.collections` area: the favourites row, the hand-made lists, and the titles filed into them. */
+import type { ApiClient } from "../../http";
+import { Resource } from "../../http";
+import type { ListParams } from "../../listing";
+import type { BaseRecord, Id, Paginated, RequestOptions } from "../../types";
+import type { MovieType } from "./types";
+/** The manual kind: a collection the user created and may rename or delete. */
+export declare const MOVIE_COLLECTION_MANUAL_KIND = "manual";
+/**
+ * The one system kind. There is exactly one favourites collection per user,
+ * enforced by a partial unique index on `(user_id, kind) WHERE kind <> 'manual'`.
+ */
+export declare const MOVIE_COLLECTION_FAVORITES_KIND = "favorites";
+/** Every kind the server allows. Anything else is a `400`. */
+export declare const MOVIE_COLLECTION_KINDS: readonly ["manual", "favorites"];
+/** One of {@link MOVIE_COLLECTION_KINDS}. */
+export type MovieCollectionKind = (typeof MOVIE_COLLECTION_KINDS)[number];
+/**
+ * A user's list of titles: the auto-created favourites row, or a playlist they
+ * made by hand.
+ */
+export interface MovieCollection extends BaseRecord {
+    readonly user_id: Id;
+    readonly name: string;
+    readonly kind: MovieCollectionKind;
+    /**
+     * Sort key inside the sidebar. Favourites is minted at `-1` so it sorts
+     * first; manual collections start at `max + 1`.
+     *
+     * The index has NO order of its own, so this only sorts if you ask for it -
+     * pass `order: "position:asc"`.
+     */
+    readonly position: number;
+    /**
+     * `true` for the favourites row. Mirrors `kind != "manual"`, so it is `true`
+     * for any future system kind too. Use {@link isSystemMovieCollection}.
+     */
+    readonly system: boolean;
+    /**
+     * How many items are in it. Exact - but a snapshot, and adding an item does
+     * not refresh the collection row you are holding.
+     */
+    readonly items_count: number;
+}
+/** One title filed into a collection. */
+export interface MovieCollectionItem extends BaseRecord {
+    readonly movie_collection_id: Id;
+    /** `"movie"`, `"series"`, whatever the addon called it. */
+    readonly movie_type: MovieType;
+    /** The addon's own id for the title, e.g. an IMDb id. Not a database id. */
+    readonly movie_id: string;
+    /** Denormalised metadata, so a grid renders without hitting the addon. */
+    readonly name: string | null;
+    readonly poster: string | null;
+    readonly background: string | null;
+    readonly release_info: string | null;
+    /** Sort key inside the collection, dense from `0`. See {@link MovieCollectionsNamespace.reorder}. */
+    readonly position: number;
+}
+/** Arguments for {@link MovieCollectionsNamespace.create}. */
+export interface CreateMovieCollectionInput {
+    /**
+     * Required. It is the ONLY field create reads: the owner is always the
+     * caller, `kind` is forced to `"manual"` and `position` is computed as
+     * `max(position) + 1`, so passing a kind or a position is silently ignored
+     * rather than rejected. There is no way to mint a second system collection.
+     */
+    readonly name: string;
+}
+/** Arguments for {@link MovieCollectionsNamespace.update}. */
+export interface UpdateMovieCollectionInput {
+    readonly name?: string;
+    /**
+     * Sidebar order. Nothing normalises it: two collections can hold the same
+     * position and the server will not complain, so the client owns keeping the
+     * sequence sane.
+     */
+    readonly position?: number;
+}
+/**
+ * Filters for {@link MovieCollectionsNamespace.list}.
+ *
+ * Allowlist: `id`, `name`, `kind`, `created_at`, `updated_at`. Anything else is
+ * `400 "Unknown search filter: ..."`.
+ */
+export interface ListMovieCollectionsParams extends ListParams<(typeof MOVIE_COLLECTION_FILTER_COLUMNS)[number]> {
+    /** Exact match, or `IN (...)` when given an array. */
+    readonly id?: Id | readonly Id[];
+    /**
+     * Partial, accent-folded, case-insensitive match - the `LIKE` a search box
+     * wants. NOT equality: `"fav"` matches `"Favoritos"`.
+     */
+    readonly name?: string;
+    /** Exact match. `"favorites"` finds the one system row. */
+    readonly kind?: MovieCollectionKind;
+}
+/** Filter columns of `GET /movie_collections`. */
+export declare const MOVIE_COLLECTION_FILTER_COLUMNS: readonly ["id", "name", "kind", "created_at", "updated_at"];
+/** Arguments for {@link MovieCollectionItemsNamespace.create}. */
+export interface CreateMovieCollectionItemInput {
+    readonly movie_collection_id: Id;
+    readonly movie_type: MovieType;
+    /** The addon's id for the title. Required, and part of the uniqueness key. */
+    readonly movie_id: string;
+    readonly name?: string | null;
+    readonly poster?: string | null;
+    readonly background?: string | null;
+    readonly release_info?: string | null;
+}
+/**
+ * Filters for {@link MovieCollectionItemsNamespace.list}.
+ *
+ * Allowlist: `id`, `movie_collection_id`, `movie_type`, `movie_id`,
+ * `position`, `created_at`, `updated_at`.
+ */
+export interface ListMovieCollectionItemsParams extends ListParams<(typeof MOVIE_COLLECTION_ITEM_FILTER_COLUMNS)[number]> {
+    /** Exact match, or `IN (...)` when given an array. */
+    readonly id?: Id | readonly Id[];
+    /**
+     * Exact match, or `IN (...)` for several collections at once. Almost always
+     * what you want: the bare index returns the items of EVERY collection the
+     * caller owns, interleaved.
+     */
+    readonly collectionId?: Id | readonly Id[];
+    /** Exact match. */
+    readonly movieType?: MovieType;
+    /** Exact match on the addon's title id. */
+    readonly movieId?: string;
+    /** Exact match on the sort key. */
+    readonly position?: number;
+}
+/** Filter columns of `GET /movie_collection_items`. */
+export declare const MOVIE_COLLECTION_ITEM_FILTER_COLUMNS: readonly ["id", "movie_collection_id", "movie_type", "movie_id", "position", "created_at", "updated_at"];
+/**
+ * Whether a collection is the server-managed favourites row.
+ *
+ * Prefer this over `collection.kind === "favorites"`: the server's own test is
+ * `kind != "manual"`, so a future system kind reads as system there and would
+ * read as manual in a hand-written equality check. The `system` flag already
+ * carries it; this just keeps the test in one place.
+ */
+export declare function isSystemMovieCollection(collection: Pick<MovieCollection, "kind">): boolean;
+/**
+ * The `movies.collections.items` namespace: the titles filed into a collection.
+ *
+ * Index and create and delete; there is no `show` and no `update`. To change a
+ * title's stored metadata, {@link create} it again - it upserts.
+ */
+export declare class MovieCollectionItemsNamespace extends Resource {
+    /**
+     * `GET /movie_collection_items` - items across the caller's collections.
+     *
+     * **Pass `collectionId` unless you really mean everything.** With no filter
+     * this returns the items of EVERY collection the caller owns, and because
+     * the default order is `position:asc` they come back interleaved by position
+     * rather than grouped by collection - position 0 of each list, then
+     * position 1 of each, and so on. Grouping that back together client-side
+     * works but reads like a bug when you first see it.
+     *
+     * `collectionId` accepts an array, which becomes `IN (...)`: one request for
+     * the three lists a screen shows.
+     *
+     * The default order is `position:asc` and it is the useful one, so leave
+     * `order` alone unless you want something else. Note that passing `order`
+     * REPLACES the default, it does not add to it, so `order: "created_at:desc"`
+     * loses the position ordering entirely.
+     *
+     * @throws {OmsApiError} 400 `"Unknown search filter: ..."` outside the
+     *   allowlist in {@link ListMovieCollectionItemsParams}.
+     */
+    list(params?: ListMovieCollectionItemsParams, options?: RequestOptions): Promise<Paginated<MovieCollectionItem>>;
+    /**
+     * `POST /movie_collection_items` - adds a title to a collection, or refreshes
+     * the one already there. **`201` either way.**
+     *
+     * Adding the same title twice is a no-op-with-an-update rather than a `400`
+     * off the unique index. This is deliberate: the heart button and the "add
+     * to list" dialog both fire blind, holding only the collection they already
+     * loaded. The upshot is that this call is safe to repeat and safe to fire
+     * optimistically.
+     *
+     * Two consequences worth knowing:
+     *
+     * - `position` is only computed for a NEW row (`max(position) + 1`, starting
+     *   at `0`). Re-adding an existing title keeps its place in the list rather
+     *   than moving it to the end.
+     * - the denormalised metadata (`name`, `poster`, `background`,
+     *   `release_info`) IS overwritten every time, so re-posting is how you
+     *   refresh a poster that the addon has since changed. Sending `null` for one
+     *   clears it; omitting the key leaves the stored value alone.
+     *
+     * A `movie_collection_id` that does not exist, or belongs to somebody else,
+     * is `401 "You are not authorized to create this resource"` and NOT a `404`:
+     * the ownership check fails the same way for a missing collection as for
+     * somebody else's. Do not read that `401` as "the session expired".
+     *
+     * Adding to the favourites collection is allowed - the system flag blocks
+     * renaming, reordering and deleting the COLLECTION, not writing items into
+     * it. That is how the heart button works.
+     *
+     * @throws {OmsError} `invalid_request` when the collection id, type or movie
+     *   id is blank.
+     * @throws {OmsApiError} 400 `"Movie type can't be blank"` /
+     *   `"Movie can't be blank"`, 401 for a collection that is not yours.
+     */
+    create(input: CreateMovieCollectionItemInput, options?: RequestOptions): Promise<MovieCollectionItem>;
+    /**
+     * `DELETE /movie_collection_items/:id` - `204`, empty body.
+     *
+     * The id is the ITEM's primary key, not the `movie_id` the addon uses. If
+     * all you hold is a title, {@link list} it with `collectionId` and `movieId`
+     * first, or keep the item rows the collection screen already loaded.
+     *
+     * Removing leaves a gap in `position`: nothing renumbers the survivors, and
+     * the next {@link create} takes `max + 1`, so positions drift sparse over
+     * time. Only {@link MovieCollectionsNamespace.reorder} makes them dense
+     * again. Nothing depends on them being dense.
+     *
+     * @throws {OmsApiError} 404 for an item outside your collections.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+}
+/**
+ * The `movies.collections` namespace: the favourites row plus whatever lists
+ * the user built by hand.
+ */
+export declare class MovieCollectionsNamespace extends Resource {
+    /** The titles inside a collection. */
+    readonly items: MovieCollectionItemsNamespace;
+    constructor(http: ApiClient);
+    /**
+     * `GET /movie_collections` - the caller's collections, each with its
+     * `items_count`.
+     *
+     * **This call has a side effect, and it is the only one that does.**
+     * Before anything else it finds or creates the "Favoritos" row (kind
+     * `favorites`, position `-1`). The index is the only place that knows the
+     * user has opened the movies app, so it is where the row gets minted. Two
+     * consequences: a brand new account's first listing WRITES to the database,
+     * and there is no other way to make favourites exist - a client that goes
+     * straight to the heart button without ever listing has no collection to put
+     * the title in. List first.
+     *
+     * A concurrent second tab racing the same first listing is handled: the
+     * partial unique index makes the loser read the winner's row back.
+     *
+     * `items_count` is exact here and in {@link get}. Neither is a snapshot you
+     * can trust after a write.
+     *
+     * No default order. Pass `order: "position:asc"` to get the sidebar's own
+     * order, which puts favourites first by virtue of its `-1`.
+     *
+     * @throws {OmsApiError} 401 for an anonymous caller, 403 for an OAuth token.
+     */
+    list(params?: ListMovieCollectionsParams, options?: RequestOptions): Promise<Paginated<MovieCollection>>;
+    /**
+     * Reads the caller's favourites collection, creating it if this is the first
+     * time they have opened the app.
+     *
+     * A one-line convenience over {@link list} that exists because "get me the
+     * heart list" is the single most common reason to call the index, and
+     * because doing it by hand invites filtering on `kind` client-side after a
+     * listing that may have been paged.
+     *
+     * Resolves to `null` only if the server somehow answered without the row,
+     * which should not happen - the listing mints it.
+     */
+    favorites(options?: RequestOptions): Promise<MovieCollection | null>;
+    /**
+     * `GET /movie_collections/:id` - one collection.
+     *
+     * The only `show` route in this whole namespace. Its payload is
+     * byte-identical to one row of the index: `show` is not a richer payload,
+     * only a single-row one.
+     *
+     * Unlike {@link list} it does NOT mint the favourites row.
+     *
+     * @throws {OmsApiError} 404 `"Resource not found"` for a collection that is
+     *   not yours. Ownership is the lookup scope, so somebody else's collection
+     *   and a non-existent one are indistinguishable.
+     */
+    get(id: Id, options?: RequestOptions): Promise<MovieCollection>;
+    /**
+     * `POST /movie_collections` - a new manual list. `201`.
+     *
+     * `name` is the only field that survives: the owner is always the caller,
+     * `kind` is pinned to `"manual"` and `position` is set to
+     * `max(position) + 1`. Passing `kind: "favorites"` does not fail, it is just
+     * ignored, which is the point - there is exactly one system collection and
+     * only the listing may mint it.
+     *
+     * Names are not unique.
+     *
+     * @throws {OmsApiError} 400 `"Name can't be blank"`.
+     */
+    create(input: CreateMovieCollectionInput | string, options?: RequestOptions): Promise<MovieCollection>;
+    /**
+     * `PATCH /movie_collections/:id` - renames or repositions. `200`.
+     *
+     * A real partial update: `name` and `position` are the only keys accepted,
+     * and an omitted key is left alone.
+     *
+     * Refused for the favourites row with
+     * `401 "You are not authorized to update this resource"` - the GENERIC
+     * message; the friendlier "The favourites collection cannot be renamed,
+     * reordered or deleted" is never reached here. Only {@link reorder}
+     * produces that sentence. Test with {@link isSystemMovieCollection} and hide
+     * the control instead.
+     *
+     * @throws {OmsApiError} 404 for a collection that is not yours, 401 for the
+     *   favourites row.
+     */
+    update(id: Id, input: UpdateMovieCollectionInput, options?: RequestOptions): Promise<MovieCollection>;
+    /**
+     * `DELETE /movie_collections/:id` - `204`, empty body.
+     *
+     * Cascades: every title in the list goes with it. Nothing is recoverable and
+     * nothing is asked.
+     *
+     * Refused for the favourites row with the same generic `401` as
+     * {@link update}, for the same reason.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /**
+     * `POST /movie_collections/:id/reorder` - rewrites the order of the items
+     * inside a collection. Answers `200` with the COLLECTION, not the items.
+     *
+     * Send the full ordered list of item ids. The server keeps a stale client
+     * from losing rows: ids it recognises are laid out first in the order given,
+     * then every item you did NOT mention is appended in its existing relative
+     * order, and the whole sequence is renumbered densely from `0`. So an item
+     * added by another tab between your read and your write sinks to the bottom
+     * instead of vanishing. Ids that are not in this collection are ignored, not
+     * rejected.
+     *
+     * Positions are written inside one transaction and - the part that catches
+     * people - the write does NOT touch each item's `updated_at`. A client that
+     * syncs on `updated_at` will not see a reorder. Refetch by position.
+     *
+     * The whole rewrite is one transaction, and items already at the right
+     * position are skipped, so a reorder that changes nothing costs no writes.
+     *
+     * Refused for the favourites row with
+     * `401 "The favourites collection cannot be renamed, reordered or deleted"` -
+     * this is the one action that produces that message rather than the generic
+     * one, because the system check runs before any authorisation.
+     *
+     * @throws {OmsApiError} 404 for a collection that is not yours, 401 for the
+     *   favourites row.
+     */
+    reorder(id: Id, itemIds: readonly Id[], options?: RequestOptions): Promise<MovieCollection>;
+}

package/dist/types/resources/movies/index.d.ts

@@ -0,0 +1,29 @@
+/** The `movies` namespace: Stremio addons, collections and watch progress, reachable as `oms.movies`. */
+import type { ApiClient } from "../../http";
+import { Resource } from "../../http";
+import { MovieAddonsNamespace } from "./addons";
+import { MovieCollectionsNamespace } from "./collections";
+import { MovieWatchProgressesNamespace } from "./watchProgress";
+export * from "./types";
+export * from "./addons";
+export * from "./collections";
+export * from "./watchProgress";
+/**
+ * The `movies` namespace, reachable as `oms.movies`.
+ *
+ * Everything under it needs a session or a personal token. An OAuth access
+ * token cannot reach any of it: every route answers
+ * `403 {"error":"insufficient_scope", "message": "This endpoint is not
+ * reachable with an OAuth access token..."}` - one of the few structured error
+ * bodies the API emits. That is a deliberate gate, not an oversight to route
+ * around.
+ */
+export declare class MoviesNamespace extends Resource {
+    /** Installed Stremio addons, plus `.groups` and `.grants` for sharing them. */
+    readonly addons: MovieAddonsNamespace;
+    /** Favourites and hand-made lists, plus `.items` for their contents. */
+    readonly collections: MovieCollectionsNamespace;
+    /** Playback position per title or episode; "Continuar a ver". */
+    readonly watchProgress: MovieWatchProgressesNamespace;
+    constructor(http: ApiClient);
+}

package/dist/types/resources/movies/types.d.ts

@@ -0,0 +1,50 @@
+/** Shared vocabulary of the movies namespace: title types, the Stremio manifest, and the guards every area uses. */
+/**
+ * What a title is. Stremio's own vocabulary, and the backend stores it as a
+ * free string with no inclusion validation, so an addon may invent one.
+ * Compare against this union for the cases you handle and fall through for the
+ * rest rather than assuming the list is closed.
+ */
+export type MovieType = "movie" | "series" | "channel" | "tv" | (string & {});
+/** The four resource names a Stremio manifest may advertise. */
+export type StremioResourceName = "catalog" | "meta" | "stream" | "subtitles";
+/** One catalogue an addon offers, as declared in its manifest. */
+export interface StremioCatalog {
+    readonly type: string;
+    readonly id: string;
+    readonly name?: string;
+    readonly extra?: ReadonlyArray<{
+        readonly name: string;
+        readonly isRequired?: boolean;
+        readonly options?: readonly string[];
+    }>;
+}
+/**
+ * An addon's `manifest.json`, stored verbatim in a `jsonb` column.
+ *
+ * The backend does not validate a single key of it beyond "not blank": it is
+ * written straight to the column and read straight back. So the fields below
+ * are what a well-behaved Stremio addon sends, not a contract the server
+ * enforces - `id` and `name` can be missing on a hostile or broken manifest
+ * even though they are typed as required here, and the index signature is
+ * there because whatever else the addon declared round-trips untouched.
+ *
+ * Never trust `logo`, `background` or any URL inside one without checking the
+ * origin: this blob is user-supplied content that the app renders.
+ */
+export interface StremioManifest {
+    readonly id: string;
+    readonly name: string;
+    readonly description?: string;
+    readonly version?: string;
+    readonly resources?: ReadonlyArray<StremioResourceName | {
+        readonly name: StremioResourceName;
+        readonly types?: readonly string[];
+    }>;
+    readonly types?: readonly string[];
+    readonly catalogs?: readonly StremioCatalog[];
+    readonly logo?: string;
+    readonly background?: string;
+    /** Anything else the manifest carried. `jsonb` keeps it all. */
+    readonly [key: string]: unknown;
+}