@omelhorsite/sdk 0.3.0 → 0.4.1

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

@@ -0,0 +1,277 @@
+/** The `movies.watchProgress` area: how far into each title the user got, and what "Continuar a ver" is built from. */
+import { Resource } from "../../http";
+import type { BaseRecord, Id, RequestOptions, Timestamp } from "../../types";
+import type { MovieType } from "./types";
+/**
+ * Fraction of the runtime that counts as watched when the server derives
+ * `finished` itself.
+ */
+export declare const MOVIE_WATCH_FINISHED_THRESHOLD = 0.95;
+/**
+ * Rows `POST /movie_watch_progresses/bulk` will accept in one call.
+ *
+ * The server keeps the first 200 entries: the rest are dropped in SILENCE and
+ * the call still answers `200` with the 200 rows it did save, so a client
+ * marking a 300-episode series watched would believe it succeeded.
+ * {@link MovieWatchProgressesNamespace.saveMany} raises instead.
+ */
+export declare const MOVIE_WATCH_BULK_LIMIT = 200;
+/**
+ * Rows `GET /movie_watch_progresses` returns, at most. Hard-coded, with no
+ * paging and no way to reach row 501 - see
+ * {@link MovieWatchProgressesNamespace.list}.
+ */
+export declare const MOVIE_WATCH_LIST_LIMIT = 500;
+/** One title-or-episode the user has started, and how far in they got. */
+export interface MovieWatchProgress extends BaseRecord {
+    readonly user_id: Id;
+    readonly movie_type: MovieType;
+    /** The addon's id for the TITLE. A series shares it across every episode. */
+    readonly movie_id: string;
+    /**
+     * The addon's id for the specific playable. For a film this is usually the
+     * same string as `movie_id`; for a series it is the episode.
+     *
+     * `(user_id, movie_id, video_id)` is the row's identity and carries a unique
+     * index.
+     */
+    readonly video_id: string;
+    readonly season: number | null;
+    readonly episode: number | null;
+    readonly name: string | null;
+    readonly episode_title: string | null;
+    readonly poster: string | null;
+    /** Seconds into the playable. A float, `NOT NULL DEFAULT 0.0`. */
+    readonly position: number;
+    /** Runtime in seconds, as the player measured it. `0` when unknown. */
+    readonly duration: number;
+    /** See {@link MovieWatchProgressInput.finished} for how this gets its value. */
+    readonly finished: boolean;
+    /** What "Continuar a ver" sorts on, descending. */
+    readonly last_watched_at: Timestamp;
+}
+/**
+ * One row to upsert, through {@link MovieWatchProgressesNamespace.save} or
+ * {@link MovieWatchProgressesNamespace.saveMany}.
+ *
+ * `movie_id`, `video_id` and `movie_type` are checked up front and a missing
+ * one is `400 "movie_id, video_id, movie_type are required"`. Everything else
+ * is optional, but read the notes on `finished` and `last_watched_at` before
+ * leaving them out: both are cases where omitting the field does something
+ * other than "leave it as it was".
+ */
+export interface MovieWatchProgressInput {
+    readonly movie_type: MovieType;
+    /** Identity, with `video_id`. Changing `movie_type` does NOT make a new row. */
+    readonly movie_id: string;
+    /** Identity, with `movie_id`. */
+    readonly video_id: string;
+    readonly season?: number | null;
+    readonly episode?: number | null;
+    readonly name?: string | null;
+    readonly episode_title?: string | null;
+    readonly poster?: string | null;
+    /** Seconds into the playable. Negative is `400 "Position must be greater than or equal to 0"`. */
+    readonly position?: number;
+    /** Runtime in seconds. Negative is a `400` the same way. */
+    readonly duration?: number;
+    /**
+     * Three states, not two.
+     *
+     * - **omitted** - the server derives it:
+     *   `finished = position >= duration * 0.95`, and if `duration <= 0` it
+     *   leaves the stored flag ALONE. This is what a playback tick should send.
+     * - **`true` / `false`** - the user said so. The value is written as given,
+     *   even when `duration <= 0`.
+     * - **`null`** - dropped before it is read, and therefore identical to
+     *   omitting it.
+     *
+     * That last branch is the bug that was fixed here. "Marcar como nao visto"
+     * sends `position: 0, duration: 0`, which used to hit the `duration <= 0`
+     * guard and leave `finished` true forever. Sending an explicit `false` is
+     * what makes it stick - sending `null`, or leaving the key out, still does
+     * nothing at all. {@link MovieWatchProgressesNamespace.setWatched} spells it
+     * out so you cannot get this wrong by accident.
+     *
+     * An explicit value only pins the flag for THAT save. The next tick that
+     * omits `finished` goes back to deriving it from the position.
+     */
+    readonly finished?: boolean;
+    /**
+     * When the user last watched, ISO-8601.
+     *
+     * SEND IT ON EVERY CALL. It is only defaulted when the row is first
+     * created - so an upsert that omits it keeps whatever timestamp was there
+     * when the row was first created. The Continue Watching list is ordered by
+     * it, descending, so omitting this pins the title where it first appeared
+     * and it never moves back to the front. `new Date().toISOString()` at the
+     * call site is the whole fix.
+     */
+    readonly last_watched_at?: Timestamp;
+}
+/**
+ * The same arithmetic the server uses, for a client that wants to render a
+ * "watched" tick before the round trip lands.
+ *
+ * Returns `null` - not `false` - when `duration` is zero or negative, because
+ * that is precisely the case where the server declines to decide and leaves the
+ * stored flag untouched. Treating that as `false` is how an optimistic UI ends
+ * up un-ticking something the server still considers watched.
+ */
+export declare function movieWatchFinished(position: number, duration: number): boolean | null;
+/**
+ * The `movies.watchProgress` namespace: how far into each title the user got,
+ * and what "Continuar a ver" is built from.
+ *
+ * This family is the odd one out: none of the list DSL applies, `create`
+ * answers `200`, and there is no `show` and no `update`. Everything is an
+ * upsert keyed on `(user, movie_id, video_id)`.
+ */
+export declare class MovieWatchProgressesNamespace extends Resource {
+    /**
+     * `GET /movie_watch_progresses` - the caller's rows, newest first.
+     *
+     * Not paginated, and not filterable. The query string is ignored entirely
+     * and the answer is always the 500 most recently watched rows, so:
+     *
+     * - there is NO way to reach row 501. A user with more history than that
+     *   simply cannot read the tail through this API;
+     * - `search[...]` / `exact_search[...]` / `modifiers[...]` are not rejected,
+     *   they are silently ignored - this index never raises
+     *   `400 "Unknown search filter"`. A client that thinks it asked for one
+     *   title gets all 500 rows and, if it trusts the filter, the wrong answer.
+     *   Filter client-side; that is why this method takes no params;
+     * - there is no `ETag` either.
+     *
+     * Finished rows are included. Build "Continuar a ver" by dropping
+     * `finished === true` yourself, and remember an episode can be finished while
+     * its series is not.
+     *
+     * @throws {OmsApiError} 401 for an anonymous caller, 403 for an OAuth token.
+     */
+    list(options?: RequestOptions): Promise<MovieWatchProgress[]>;
+    /**
+     * `POST /movie_watch_progresses` - upserts ONE row. **`200`, not `201`.**
+     *
+     * This is the playback tick: call it while something is playing, throttled
+     * by the player to whatever interval you like. The server finds by
+     * `(user, movie_id, video_id)` and updates in place, so it is idempotent and
+     * safe to repeat - the only create in this file where opting into
+     * `options.retry` is a good idea rather than a way to make duplicates.
+     * (The transport does not replay non-safe methods unless you ask.)
+     *
+     * `movie_type` is NOT part of the key. Posting the same `(movie_id,
+     * video_id)` with a different type rewrites the existing row's type rather
+     * than creating a second one.
+     *
+     * Read {@link MovieWatchProgressInput.finished} and
+     * {@link MovieWatchProgressInput.last_watched_at} before using this: a tick
+     * that omits `last_watched_at` does not move the title up the list, and
+     * `finished` has three states rather than two. A `finished` of `null` is
+     * dropped by this method rather than sent, matching what the server would do
+     * with it, so `finished` reaches the wire only as a real boolean.
+     *
+     * Use {@link saveMany} instead when you have more than a couple of rows -
+     * see its docs for why one request is not just faster but differently shaped.
+     *
+     * @throws {OmsError} `invalid_request` when `movie_id`, `video_id` or
+     *   `movie_type` is blank.
+     * @throws {OmsApiError} 400 `"movie_id, video_id, movie_type are required"`
+     *   from the server's own check, or a validation sentence such as
+     *   `"Position must be greater than or equal to 0"`.
+     */
+    save(input: MovieWatchProgressInput, options?: RequestOptions): Promise<MovieWatchProgress>;
+    /**
+     * `POST /movie_watch_progresses/bulk` - upserts up to
+     * {@link MOVIE_WATCH_BULK_LIMIT} rows in ONE request and ONE transaction.
+     * `200`, with the saved rows in the order sent.
+     *
+     * ## Why this endpoint exists, and when to reach for it
+     *
+     * "Marcar temporada como vista" is one row per episode. A 24-episode season
+     * through {@link save} is 24 POSTs: 24 round trips, 24 chances for one to
+     * fail and leave the season half-marked, and 24 requests against the
+     * caller's 600/min ceiling. This collapses it into one.
+     *
+     * The transaction is the other half of the point, and it cuts both ways:
+     *
+     * - **use {@link saveMany}** for a statement about several rows at once that
+     *   must be all-or-nothing - mark a season watched or unwatched, restore a
+     *   device's offline queue, seed history on first sync. If any entry is
+     *   invalid the whole batch rolls back and answers `400`, so you never end up
+     *   with episodes 1-9 marked and 10-24 not.
+     * - **use {@link save}** for the continuous playback tick. One row, and a
+     *   failure costs one tick that the next one will overwrite anyway. Batching
+     *   ticks would trade a lost second for a lost minute.
+     *
+     * ## The silent-truncation trap this method closes
+     *
+     * The server keeps the first 200 entries: the rest are dropped without a
+     * word and the response is a cheerful `200` listing the 200 that were saved.
+     * A 300-episode batch would look like it worked. This method raises before
+     * sending instead, so split the work yourself - and note that separate
+     * batches are separate transactions, so a split is no longer atomic end to
+     * end.
+     *
+     * Retrying the whole batch is safe: every entry is the same upsert
+     * {@link save} performs.
+     *
+     * @throws {OmsError} `invalid_request` for an empty list, for more than
+     *   {@link MOVIE_WATCH_BULK_LIMIT} entries, or for an entry missing
+     *   `movie_id`, `video_id` or `movie_type`.
+     * @throws {OmsApiError} 400 `"items is required"` for an empty list that got
+     *   through, or the first failing entry's validation sentence - and in that
+     *   case NOTHING was saved.
+     */
+    saveMany(inputs: readonly MovieWatchProgressInput[], options?: RequestOptions): Promise<MovieWatchProgress[]>;
+    /**
+     * Marks one playable watched or unwatched, explicitly.
+     *
+     * Sugar over {@link save} that exists because this is the exact call the
+     * fixed bug was about. Marking something UNWATCHED sends `position: 0,
+     * duration: 0`, and with `finished` absent the server's `duration <= 0`
+     * guard leaves the stored flag as it was - so the tick never came off.
+     * Passing the boolean outright skips that guard and writes what you said.
+     *
+     * Defaults `position` and `duration` to `0` when you do not supply them,
+     * which is right for "mark unwatched" and harmless for "mark watched"
+     * precisely because the explicit flag stops the server deriving anything from
+     * them. Supply the real numbers when you have them; the progress bar reads
+     * them.
+     *
+     * `last_watched_at` is still yours to send, and still matters: marking an
+     * episode watched without one leaves the series where it was in the list.
+     */
+    setWatched(input: Omit<MovieWatchProgressInput, "finished">, watched: boolean, options?: RequestOptions): Promise<MovieWatchProgress>;
+    /**
+     * `DELETE /movie_watch_progresses/:id` - forgets ONE playable. `204`, empty
+     * body.
+     *
+     * The id is the progress row's primary key, which for a series is one
+     * episode. To forget a whole title use {@link forgetMovie}.
+     *
+     * @throws {OmsApiError} 404 `"Resource not found"` for a row that is not
+     *   yours.
+     */
+    delete(id: Id, options?: RequestOptions): Promise<void>;
+    /**
+     * `DELETE /movie_watch_progresses/for_movie?movie_id=...` - forgets EVERY row
+     * for a title. `204`, empty body.
+     *
+     * This is the "remover de Continuar a ver" button. For a series it destroys
+     * the progress of every episode, not just the one on screen; there is no
+     * per-season form and no undo.
+     *
+     * Note the verb: despite the `?movie_id=` query string this is a **DELETE**,
+     * not a read. It is a collection route, so the `movie_id` is the addon's id
+     * for the title (an IMDb id, say), never a `movie_watch_progresses` primary
+     * key.
+     *
+     * `204` even when nothing matched, so the answer does not tell you whether
+     * anything was there.
+     *
+     * @throws {OmsError} `invalid_request` for a blank id.
+     * @throws {OmsApiError} 400 `"movie_id is required"`.
+     */
+    forgetMovie(movieId: string, options?: RequestOptions): Promise<void>;
+}

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

@@ -24,24 +24,19 @@
  *    OAuth access token gets `403 {"error":"insufficient_scope"}` on every
  *    route in this file. Cookie sessions and personal tokens work; third-party
  *    OAuth clients do not. See {@link MoviesNamespace}.
- * 3. **`PATCH /movie_addons/:id` wipes `manifest_json` unless you resend it.**
- *    The controller assigns the key unconditionally, so a partial patch sends
- *    `nil` into a `presence: true` validation and answers `400`. That is why
- *    {@link UpdateMovieAddonInput.manifest_json} is REQUIRED here, and why
- *    {@link MovieAddonsNamespace.moveToGroup} exists.
- * 4. **Listing collections has a side effect**: it is the only place that
+ * 3. **Listing collections has a side effect**: it is the only place that
  *    creates the user's "Favoritos" row. See
  *    {@link MovieCollectionsNamespace.list}.
- * 5. **`POST /movie_watch_progresses` is an upsert that answers `200`, not
+ * 4. **`POST /movie_watch_progresses` is an upsert that answers `200`, not
  *    `201`**, and its identity is `(user, movie_id, video_id)` - `movie_type`
  *    is NOT part of the key. It is one of the very few creates in the API that
  *    breaks the 201 convention, because it is not really a create.
- * 6. **`finished` is a three-state field, not a boolean.** Omitted means "you
+ * 5. **`finished` is a three-state field, not a boolean.** Omitted means "you
  *    decide from the position"; `true`/`false` means "the user said so". A
  *    `null` is deleted by the controller and reads as omitted, which is
  *    exactly the bug that once made "marcar como nao visto" silently do
  *    nothing. See {@link MovieWatchProgressInput.finished}.
- * 7. **`last_watched_at` is only defaulted on INSERT.** The model does
+ * 6. **`last_watched_at` is only defaulted on INSERT.** The model does
  *    `self.last_watched_at ||= Time.current`, so an upsert onto an existing row
  *    that omits it keeps the OLD timestamp - and the Continue Watching list is
  *    ordered by exactly that column. Always send one. See
@@ -53,7 +48,8 @@
  * never applies.
  */
 import { ApiClient, Resource } from "../http";
-import type { BaseRecord, Id, PageParams, Paginated, RequestOptions, Timestamp } from "../types";
+import type { ListParams } from "../listing";
+import type { BaseRecord, Id, Paginated, RequestOptions, Timestamp } from "../types";
 import type { User } from "./account";
 /**
  * What a title is. Stremio's own vocabulary, and the backend stores it as a
@@ -151,22 +147,10 @@ export interface CreateMovieAddonInput {
      */
     readonly movie_addon_group_id?: Id | null;
 }
-/**
- * Arguments for {@link MovieAddonsNamespace.update}.
- *
- * `manifest_json` is required, and that is not an oversight to work around.
- * `MovieAddonsController#movie_addon_params` is shared by create and update and
- * ends with an unconditional `permitted[:manifest_json] = params[:manifest_json]`,
- * so a PATCH that omits the key assigns `nil` over the stored manifest and then
- * trips `validates :manifest_json, presence: true`. The row survives (the save
- * failed) but the call is a `400`, which is how `moveAddonToGroup` in the web
- * frontend is broken today - it sends `{ movie_addon_group_id }` alone. Resend
- * the manifest you already hold; {@link MovieAddonsNamespace.moveToGroup} does
- * it for you.
- */
+/** Arguments for {@link MovieAddonsNamespace.update}. Every field is optional; omitted ones are left alone. */
 export interface UpdateMovieAddonInput {
-    /** Resend the stored manifest verbatim. See the interface docs for why. */
-    readonly manifest_json: StremioManifest;
+    /** A replacement manifest. Must be a non-empty object. */
+    readonly manifest_json?: StremioManifest;
     /** `null` un-groups the addon. Omitting the key leaves the group alone. */
     readonly movie_addon_group_id?: Id | null;
     /**
@@ -185,12 +169,14 @@ export interface UpdateMovieAddonInput {
  * the query - so there is deliberately no way to list by
  * `movie_addon_group_id`. Group client-side off the field on each row.
  */
-export interface ListMovieAddonsParams extends PageParams {
+export interface ListMovieAddonsParams extends ListParams<(typeof MOVIE_ADDON_FILTER_COLUMNS)[number]> {
     /** Exact match. Use it to split your own addons from the shared ones. */
     readonly userId?: Id;
     /** Exact match on the primary key. */
     readonly id?: Id;
 }
+/** Filter columns of `GET /movie_addons`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const MOVIE_ADDON_FILTER_COLUMNS: readonly ["user_id"];
 /** Arguments for {@link MovieAddonGroupsNamespace.create}. */
 export interface CreateMovieAddonGroupInput {
     /** Required, at most {@link MOVIE_ADDON_GROUP_NAME_MAX_LENGTH} characters. */
@@ -207,10 +193,12 @@ export interface MovieAddonGroup extends BaseRecord {
     readonly name: string;
 }
 /** Filters for {@link MovieAddonGroupsNamespace.list}. */
-export interface ListMovieAddonGroupsParams extends PageParams {
+export interface ListMovieAddonGroupsParams extends ListParams<never> {
     /** Exact match on the primary key. The only filter this index allows. */
     readonly id?: Id;
 }
+/** `GET /movie_addon_groups` filters on {@link BASE_FILTER_COLUMNS} only. */
+export declare const MOVIE_ADDON_GROUP_FILTER_COLUMNS: readonly [];
 /**
  * A share: one addon, or one whole group, handed to one other user.
  *
@@ -265,10 +253,12 @@ export interface CreateMovieAddonGrantInput {
  * one addon - those are `400`s. Filter on `grantor_id` / `grantee_id` /
  * `movie_addon_id` client-side after listing.
  */
-export interface ListMovieAddonGrantsParams extends PageParams {
+export interface ListMovieAddonGrantsParams extends ListParams<never> {
     /** Exact match on the primary key. */
     readonly id?: Id;
 }
+/** `GET /movie_addon_grants` filters on {@link BASE_FILTER_COLUMNS} only. */
+export declare const MOVIE_ADDON_GRANT_FILTER_COLUMNS: readonly [];
 /** The manual kind: a collection the user created and may rename or delete. */
 export declare const MOVIE_COLLECTION_MANUAL_KIND = "manual";
 /**
@@ -351,7 +341,7 @@ export interface UpdateMovieCollectionInput {
  * Allowlist: `id`, `name`, `kind`, `created_at`, `updated_at`. Anything else is
  * `400 "Unknown search filter: ..."`.
  */
-export interface ListMovieCollectionsParams extends PageParams {
+export interface ListMovieCollectionsParams extends ListParams<(typeof MOVIE_COLLECTION_FILTER_COLUMNS)[number]> {
     /** Exact match, or `IN (...)` when given an array. */
     readonly id?: Id | readonly Id[];
     /**
@@ -362,6 +352,8 @@ export interface ListMovieCollectionsParams extends PageParams {
     /** 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;
@@ -379,7 +371,7 @@ export interface CreateMovieCollectionItemInput {
  * Allowlist: `id`, `movie_collection_id`, `movie_type`, `movie_id`,
  * `position`, `created_at`, `updated_at`.
  */
-export interface ListMovieCollectionItemsParams extends PageParams {
+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[];
     /**
@@ -395,6 +387,8 @@ export interface ListMovieCollectionItemsParams extends PageParams {
     /** 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"];
 /**
  * Fraction of the runtime that counts as watched when the server derives
  * `finished` itself. Mirrors `MovieWatchProgress::FINISHED_THRESHOLD`.
@@ -730,25 +724,10 @@ export declare class MovieAddonsNamespace extends Resource {
      */
     create(input: CreateMovieAddonInput, options?: RequestOptions): Promise<MovieAddon>;
     /**
-     * `PATCH /movie_addons/:id` - `200`.
+     * `PATCH /movie_addons/:id` - `200`. A partial update: omitted fields are
+     * left alone. Only the owner may update; a shared row is `401`.
      *
-     * **This is not a partial update, whatever the verb says.**
-     * `movie_addon_params` is shared between create and update and finishes with
-     * an unconditional `permitted[:manifest_json] = params[:manifest_json]`, so
-     * the key is always assigned - as `nil` when you did not send one. `nil` then
-     * fails `validates :manifest_json, presence: true` and the whole call is
-     * `400 "Manifest json can't be blank"`. Nothing is written; the row is fine.
-     * It simply cannot be patched without resending the manifest.
-     *
-     * That is a live divergence: the web frontend's
-     * `MovieAddonsService.update(id, { movie_addon_group_id })` sends the group
-     * alone and therefore 400s. {@link UpdateMovieAddonInput.manifest_json} is
-     * required here so the same mistake is a compile error, and
-     * {@link moveToGroup} carries the manifest across for you.
-     *
-     * Only the owner may update: a shared row is `401`.
-     *
-     * @throws {OmsError} `invalid_request` when `manifest_json` is missing or empty.
+     * @throws {OmsError} `invalid_request` when `manifest_json` is given but empty.
      * @throws {OmsApiError} 404 for an id you cannot see, 401 for one you can see
      *   but do not own.
      */
@@ -756,11 +735,6 @@ export declare class MovieAddonsNamespace extends Resource {
     /**
      * Files an addon under a group, or un-groups it with `null`.
      *
-     * Sugar over {@link update} that exists purely because the endpoint demands
-     * the manifest back on every patch. Pass the {@link MovieAddon} you already
-     * hold and its `manifest_json` is resent unchanged; there is no extra request
-     * and no fetch of the manifest.
-     *
      * Refuses a shared addon before the round trip: the server would answer
      * `401`, and the message here says why.
      *