@omelhorsite/sdk 0.3.0 → 0.4.1

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

@@ -1,13 +1,12 @@
 /**
- * The `realtime` namespace: ActionCable over a raw WebSocket.
+ * The `realtime` namespace: Action Cable over a raw WebSocket.
  *
- * This is the only transport in the SDK that is not HTTP, and it is the reason
- * "the frontend uses 100% of the SDK" can be true rather than nearly true.
- * Everything else here talks to `/`-rooted JSON endpoints through
- * {@link ApiClient}; this talks the ActionCable v1 wire protocol to `/cable`,
- * and it deliberately does NOT depend on `@rails/actioncable` - that package
- * assumes a browser, pulls in its own global logger, and is bigger than the
- * eighty lines of protocol it implements.
+ * This is the only transport in the SDK that is not HTTP. Everything else
+ * talks to `/`-rooted JSON endpoints through {@link ApiClient}; this talks the
+ * Action Cable v1 wire protocol to `/cable`, and it deliberately does NOT
+ * depend on `@rails/actioncable` - that package assumes a browser, pulls in
+ * its own global logger, and is bigger than the eighty lines of protocol it
+ * implements.
  *
  * ## The protocol, in full
  *
@@ -36,46 +35,41 @@
  * ## The identifier is a string, and it is compared as one
  *
  * `identifier` is a JSON-encoded string such as `'{"channel":"PlaybackChannel"}'`.
- * The server echoes back the exact bytes it received and Rails routes incoming
- * frames by looking that string up in a map. Re-serialising with the keys in a
+ * The server echoes back the exact bytes it received and routes incoming
+ * frames by looking that string up. Re-serialising with the keys in a
  * different order produces a different string, the lookup misses, and the
  * symptom is not an error: it is a subscription that confirms and then never
  * receives anything. So this module builds the identifier ONCE per
  * subscription, keys its own registry by that same string, and never rebuilds
  * it - including across a reconnect.
  *
- * ## Four traps, all of them confirmed against the Rails source
+ * ## Four traps
  *
  * 1. **The handshake authenticates on the FIRST candidate, with no fallback.**
- *    `ApplicationCable::Connection#find_session` calls
- *    `Session.token_from_request`, which is `candidate_tokens(request).first`:
- *    the `Authorization` header, then `?token=`, then the session cookie, and
- *    it takes the first one that is merely NON-BLANK. Contrast the HTTP path,
- *    which uses `Session.resolve_from_request` and tries each candidate until
- *    one resolves to a live session. A stale `Authorization` header therefore
- *    shadows a perfectly good cookie on the cable and on the cable only. This
- *    module never sends an `Authorization` header on the handshake (browsers
- *    cannot attach one to a WebSocket anyway) and puts the token in the query
- *    string, exactly as `oms-music` does.
- * 2. **Anonymous connections are ACCEPTED.** `connect` sets `current_user` to
- *    `nil` and returns; it does not `reject_unauthorized_connection`. A bad
- *    token, an expired token, or no token at all produces a perfectly healthy
- *    socket that says `welcome` and then pings forever. The identity failure
- *    surfaces ONE LEVEL DOWN, as `reject_subscription` on each channel that
- *    needs a user. A client that only handles connection errors will sit there
- *    believing it is signed in. Handle {@link CableHandlers.onReject}, always.
- * 3. **Only legacy `Session` tokens work.** `find_session` ends in
- *    `Session.find_by(token:)` - it never looks at `oauth_access_tokens`. An
- *    OAuth access token that authenticates every REST call in this SDK
- *    produces an ANONYMOUS cable connection, i.e. trap 2. There is no scope
- *    that fixes this and no error that says it; you get silent rejections on
- *    every channel. Cable access needs a session token or the session cookie.
- * 4. **`/cable` is exempt from the rate limits.** It is on rack-attack's
- *    allowlist, so neither the 600/min authed ceiling nor the 120/min anonymous
- *    one applies to the handshake or to anything sent over the socket. That is
- *    a convenience for `position_tick` at 1 Hz, not a licence: the reconnect
- *    backoff below exists because an unthrottled reconnect loop against a
- *    restarting server is a self-inflicted denial of service.
+ *    The `Authorization` header, then `?token=`, then the session cookie: the
+ *    handshake takes the first one that is merely NON-BLANK. The HTTP API
+ *    tries each candidate until one resolves to a live session; the cable does
+ *    not. A stale `Authorization` header therefore shadows a perfectly good
+ *    cookie on the cable and on the cable only. This module never sends an
+ *    `Authorization` header on the handshake (browsers cannot attach one to a
+ *    WebSocket anyway) and puts the token in the query string.
+ * 2. **Anonymous connections are ACCEPTED.** A bad token, an expired token, or
+ *    no token at all produces a perfectly healthy socket that says `welcome`
+ *    and then pings forever. The identity failure surfaces ONE LEVEL DOWN, as
+ *    `reject_subscription` on each channel that needs a user. A client that
+ *    only handles connection errors will sit there believing it is signed in.
+ *    Handle {@link CableHandlers.onReject}, always.
+ * 3. **Only session tokens work.** An OAuth access token that authenticates
+ *    every REST call in this SDK produces an ANONYMOUS cable connection, i.e.
+ *    trap 2. There is no scope that fixes this and no error that says it; you
+ *    get silent rejections on every channel. Cable access needs a session
+ *    token or the session cookie.
+ * 4. **`/cable` is exempt from the rate limits.** Neither the 600 requests a
+ *    minute authed ceiling nor the 120 a minute anonymous one applies to the
+ *    handshake or to anything sent over the socket. That is a convenience for
+ *    `position_tick` at 1 Hz, not a licence: the reconnect backoff below
+ *    exists because an unthrottled reconnect loop against a restarting server
+ *    is a self-inflicted denial of service.
  *
  * ## Injecting the socket
  *
@@ -254,7 +248,7 @@ export interface CableSubscription {
     readonly active: boolean;
 }
 /**
- * Every channel class under `backend/app/channels`, as of this writing.
+ * Every channel the server exposes, as of this writing.
  *
  * There are exactly five, and none of them is generic: each has its own
  * subscription params, its own rejection rule, and its own message vocabulary.
@@ -273,26 +267,22 @@ export type CableChannelName = (typeof CABLE_CHANNELS)[number];
 /**
  * The playback state as the cable serialises it.
  *
- * **The id types here are not the ones the app docs promise.** `oms-music`'s
- * `API.md` says flatly that "on the cable, song ids and queue entries are
- * STRINGS". Half of that is true and the Rails source says which half:
+ * **Two id fields, two types.**
  *
- * - `queue` is a `jsonb` column that the channel writes as
- *   `Array(attrs["queue"]).map(&:to_s)`, so it really is `string[]` coming
- *   back, whatever the client sent;
- * - `song_id` is a `bigint` COLUMN (`db/schema.rb`, `playback_states`). You
- *   send it as a string, Rails casts it on write, and it comes back as a JSON
- *   NUMBER. It is not a string, and code that does `state.song_id === queue[i]`
- *   compares a number to a string and silently never matches.
+ * - `queue` really is `string[]` coming back, whatever the client sent: the
+ *   server stringifies it on write;
+ * - `song_id` is sent as a string and comes back as a JSON NUMBER. Code that
+ *   does `state.song_id === queue[i]` compares a number to a string and
+ *   silently never matches.
  *
  * The rule that does hold everywhere is: normalise with `String(...)` at the
  * boundary and compare strings. This SDK types the fields as the wire actually
- * carries them rather than as the doc wishes they were, so the mismatch is a
- * type error at your call site instead of a bug at runtime.
+ * carries them, so the mismatch is a type error at your call site instead of a
+ * bug at runtime.
  */
 export interface PlaybackSnapshotState {
     readonly active_device_id: string | null;
-    /** v1 shim, dies with the column-prune migration. */
+    /** v1 shim, scheduled for removal. */
     readonly active_session_id: string | null;
     /** A NUMBER, not a string. See the note on this interface. */
     readonly song_id: number | null;
@@ -321,7 +311,7 @@ export interface PlaybackSnapshotState {
     readonly vocal_volume: number;
     readonly instrumental_volume: number;
     /**
-     * The full blueprint of every queued song - by far the heaviest part of the
+     * The full record of every queued song - by far the heaviest part of the
      * payload, and OMITTED whenever the queue itself did not change.
      *
      * This is the single most misread field on the cable. `state_changed` for a
@@ -439,11 +429,11 @@ export type PlaybackMessage = {
     readonly reason: string;
 };
 /**
- * The remote-control vocabulary, exactly as `COMMAND_SCHEMAS` lists it.
+ * The remote-control vocabulary.
  *
  * A name outside this set is answered with `error: unknown_command` and never
- * reaches a broadcast. `jam_add_song` is missing on purpose: it is server-built
- * in `JamsController` so a client cannot forge a jam proposal.
+ * reaches a broadcast. `jam_add_song` is missing on purpose: the server builds
+ * it itself so a client cannot forge a jam proposal.
  */
 export type PlaybackCommandName = "play" | "pause" | "toggle" | "next" | "previous" | "seek" | "set_queue_index" | "set_queue_order" | "set_shuffle" | "set_loop_mode" | "set_volume" | "add_to_queue" | "play_next" | "remove_from_queue" | "reorder_queue";
 /** Subscription params for `PlaybackChannel`. */
@@ -477,7 +467,7 @@ export interface PlaybackSubscribeParams {
  * `perform` is still there for anything added server-side before this file
  * catches up, but every action the channel defines today has a method, because
  * the argument shapes are validated strictly and a typo in an action name is
- * silently ignored by ActionCable rather than reported.
+ * silently ignored by the server rather than reported.
  */
 export interface PlaybackSubscription extends CableSubscription {
     /**
@@ -580,7 +570,7 @@ export type JamMessage = {
     readonly jam: unknown;
 } | {
     readonly type: "song_proposed";
-    /** `song.id` is an INTEGER here - this payload is built by the controller. */
+    /** `song.id` is an INTEGER here. */
     readonly song: {
         readonly id: number;
         readonly title: string;
@@ -593,7 +583,7 @@ export type JamMessage = {
     };
 } | {
     readonly type: "skip_votes";
-    /** The host's `PlaybackState#song_id`: a NUMBER, not a string. */
+    /** The host's playback `song_id`: a NUMBER, not a string. */
     readonly song_id: number | null;
     readonly count: number;
     readonly needed: number;
@@ -646,7 +636,7 @@ export type FriendListeningMessage = {
 export interface JobMessage {
     /** Always `"snapshot"`, on subscribe and on every change alike. */
     readonly type: "snapshot";
-    /** The `:extended` job blueprint. Finished when `finished_at` is non-null. */
+    /** The job record, as `oms.jobs.get` answers it. Finished when `finished_at` is non-null. */
     readonly job: unknown;
 }
 /** Subscription params for `JobChannel`. */
@@ -670,16 +660,16 @@ export type NotificationsMessage = {
     readonly unread_count: number;
 } | {
     readonly type: "created";
-    /** The `:extended` notification blueprint. */
+    /** The notification record. */
     readonly notification: unknown;
     readonly unread_count: number;
 };
 /**
  * One multiplexed cable connection.
  *
- * All five channels share a single WebSocket, which is what ActionCable is for:
- * the `identifier` is the demultiplexing key. Open one of these per identity
- * and keep it for the lifetime of the session.
+ * All five channels share a single WebSocket; the `identifier` is the
+ * demultiplexing key. Open one of these per identity and keep it for the
+ * lifetime of the session.
  *
  * ## What a reconnect does to your subscriptions
  *
@@ -694,13 +684,13 @@ export type NotificationsMessage = {
  * valid across all of it - you never re-subscribe by hand and you must not, or
  * you will end up with the same identifier registered twice.
  *
- * The thing to expect is that server-side subscribe-time work RUNS AGAIN,
- * because `subscribed` runs again. Concretely: `PlaybackChannel` re-registers
- * the device and re-broadcasts `devices_changed`, every channel re-transmits
- * its snapshot, and `FriendListeningChannel` re-reads the friend roster. That
- * last one is load-bearing in the other direction too - the roster is fixed at
- * subscribe time, so a new friend or a privacy flip only appears after a
- * resubscribe, which is why the app resubscribes it on foreground.
+ * The thing to expect is that server-side subscribe-time work RUNS AGAIN.
+ * Concretely: `PlaybackChannel` re-registers the device and re-broadcasts
+ * `devices_changed`, every channel re-transmits its snapshot, and
+ * `FriendListeningChannel` re-reads the friend roster. That last one is
+ * load-bearing in the other direction too - the roster is fixed at subscribe
+ * time, so a new friend or a privacy flip only appears after a resubscribe;
+ * resubscribe it on foreground.
  *
  * The thing that does NOT happen is a replay of anything you sent. Frames sent
  * while disconnected are dropped, not queued: see {@link CableSubscription.perform}.
@@ -774,9 +764,9 @@ export declare function cableEndpoint(baseUrl: string, path?: string): string;
  *
  * The token goes in the query and NOWHERE else. A browser cannot put a header
  * on a WebSocket handshake at all, and on the runtimes that can, doing so would
- * hit trap 1: `Session.token_from_request` takes the first non-blank candidate,
- * header first, so any header at all - including a stale one - decides the
- * identity and the query param is never consulted.
+ * hit trap 1: the handshake takes the first non-blank candidate, header first,
+ * so any header at all - including a stale one - decides the identity and the
+ * query param is never consulted.
  *
  * An empty string is treated as no credential, which is the cookie-auth case:
  * the handshake goes out bare and the browser attaches the httpOnly session
@@ -789,29 +779,26 @@ export declare function handshakeUrl(endpoint: string, token: string | null | un
  * It holds no socket of its own. {@link connect} builds one and hands it back,
  * so a host that needs two identities (a signed-in user and an anonymous job
  * watcher) gets two connections rather than a hidden singleton it cannot
- * separate. That is the one place this differs from both existing
- * implementations, which each keep a module-level singleton - fine for one app,
- * wrong for a library.
+ * separate.
  *
  * ## Why the credential is passed in and not taken from the client
  *
  * `Oms` already holds a credential, and this namespace deliberately does not
- * reach into it. Two reasons, both from the Rails source rather than from
- * taste:
+ * reach into it. Two reasons:
  *
- * - the cable resolves ONLY `Session` tokens (`Session.find_by(token:)`), so
- *   the OAuth access token an `Oms` may be carrying is not a cable credential
- *   at all - silently reusing it would hand you an anonymous connection;
+ * - the cable resolves ONLY session tokens, so the OAuth access token an `Oms`
+ *   may be carrying is not a cable credential at all - silently reusing it
+ *   would hand you an anonymous connection;
  * - `sessionCookie: true` clients have no token to reuse, and their handshake
  *   needs no `?token=` because the browser sends the cookie. For those, pass
  *   nothing.
  *
  * ## Rate limits
  *
- * None. `/cable` is on rack-attack's allowlist, so neither the 600/min authed
- * ceiling nor the 120/min anonymous one applies to the handshake or to any
- * frame after it. The backoff in {@link CableConnectOptions.reconnectMaxMs} is
- * therefore the only thing standing between a restarting server and a
+ * None. `/cable` is exempt, so neither the 600 requests a minute authed
+ * ceiling nor the 120 a minute anonymous one applies to the handshake or to
+ * any frame after it. The backoff in {@link CableConnectOptions.reconnectMaxMs}
+ * is therefore the only thing standing between a restarting server and a
  * reconnect storm; it is not decorative.
  */
 export declare class RealtimeNamespace extends Resource {

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

@@ -1,33 +1,28 @@
 /**
  * The `shortLinks` namespace: URL shortening plus per-link click statistics.
  *
- * This module is the reference implementation of the resource pattern. Every
- * other resource in the SDK is shaped exactly like it, and CONTRACT.md quotes
- * it verbatim. Change the pattern here and change it everywhere, or do not
- * change it at all.
- *
  * Creating a link works anonymously; listing, editing and statistics need a
  * credential. Creation is the most tightly throttled write in the whole API -
  * see {@link ShortLinksNamespace.create} before you spend one.
  *
  * There is deliberately no `get(id)` here, and its absence is the API's, not
- * an omission: the route file declares `resources :short_links, only: [:create,
- * :index, :update, :destroy]`, so `GET /short_links/:id` is not routed at all
- * and answers 404 for every id, including your own links. To read one link,
- * find it in {@link ShortLinksNamespace.list} - or by endpoint with
+ * an omission: `GET /short_links/:id` does not exist and answers 404 for every
+ * id, including your own links. To read one link, find it in
+ * {@link ShortLinksNamespace.list} - or by endpoint with
  * {@link ShortLinksNamespace.resolve}, which explains what that costs.
  */
 import { Resource } from "../http";
-import { type BaseRecord, type Id, type Json, type PageParams, type Paginated, type RequestOptions, type Timestamp } from "../types";
-/** Public host that fronts `short_links#follow`. See {@link ShortLinksNamespace.shortUrl}. */
+import type { ListParams } from "../listing";
+import { type BaseRecord, type Id, type Json, type Paginated, type RequestOptions, type Timestamp } from "../types";
+/** Public host short links are served from. See {@link ShortLinksNamespace.shortUrl}. */
 export declare const SHORT_LINK_BASE_URL = "https://omelhor.site";
 /**
  * Primary key of a short link.
  *
- * Short links predate the string ids the rest of the API uses: the table still
- * has an integer primary key, so the JSON carries a **number** here while the
- * `user_id` right next to it is a string. Every method accepts either form and
- * interpolates it into the path, so a caller never has to care.
+ * Short links predate the string ids the rest of the API uses: the JSON
+ * carries a **number** here while the `user_id` right next to it is a string.
+ * Every method accepts either form and interpolates it into the path, so a
+ * caller never has to care.
  */
 export type ShortLinkId = Id | number;
 /** One recorded visit to a short link. */
@@ -41,15 +36,15 @@ export interface ShortLinkClick {
     readonly device_name: string | null;
 }
 /**
- * The owner of a link, rendered inline by `UserBlueprint`'s default view.
+ * The owner of a link, rendered inline.
  *
- * Only the keys that view declares unconditionally are named. `UserBlueprint`
- * also renders `group`, `email`, `gender`, `last_seen_at`, `sessions_count`,
- * `deactivated_at`, `allowed_to_use_spotify` and `share_listening` behind `if:`
- * predicates that test who is ASKING, so whether they appear depends on the
- * caller's own privileges rather than on the record. That is why they are
- * reached through the index signature instead of being declared here as
- * optionals: an optional would suggest the server decides, and it does not.
+ * Only the keys that are always present are named. `group`, `email`,
+ * `gender`, `last_seen_at`, `sessions_count`, `deactivated_at`,
+ * `allowed_to_use_spotify` and `share_listening` appear or not depending on
+ * who is ASKING - the caller's own privileges rather than the record. That is
+ * why they are reached through the index signature instead of being declared
+ * here as optionals: an optional would suggest the record decides, and it does
+ * not.
  */
 export interface ShortLinkOwner {
     readonly id: Id;
@@ -68,11 +63,6 @@ export interface ShortLinkOwner {
  * {@link ShortLinkId} for why the identifier is a number on this one table.
  *
  * Every key below is present on every response this namespace can produce.
- * `ShortLinkBlueprint` does declare a second, narrower `:admin` view - it drops
- * `updated_at`, both associations, and adds `owner`, `click_count` and
- * `last_click_at` - but that view is only ever rendered by the admin
- * shortlinks tool under `/admin/short_links`, which is not this resource. A
- * record that arrived here has the full default shape.
  */
 export interface ShortLink extends Omit<BaseRecord, "id"> {
     /** Integer primary key. See {@link ShortLinkId}. */
@@ -86,22 +76,21 @@ export interface ShortLink extends Omit<BaseRecord, "id"> {
      * internal tools reserve `"n"` (notepads), `"c"` (chests), `"ss"` (storage
      * shares), `"qr"` (dynamic QR), `"f"` (forms) and `"t"` (link trees). That
      * is why {@link ShortLink} and `DynamicQr` are separate resources even
-     * though both are rows in the same table.
+     * though both are short links.
      *
      * A link that reached you through {@link ShortLinksNamespace.list} always
-     * holds `null` or `""`, because the listing scope is `user_managed`.
+     * holds `null` or `""`, because the listing only returns user-managed links.
      */
     readonly namespace: string | null;
     /** Owner, or `null` for a link created anonymously. */
     readonly user_id: Id | null;
     /**
-     * EVERY click ever recorded, inlined by the blueprint - not a count, not a
-     * page. A link with 50 000 visits sends 50 000 objects here. Use
+     * EVERY click ever recorded, inlined - not a count, not a page. A link with
+     * 50 000 visits sends 50 000 objects here. Use
      * {@link ShortLinksNamespace.stats} for anything analytical and treat this
      * field as a payload hazard, not as a feature.
      *
-     * Always present, and `[]` rather than `null` for a link nobody has clicked:
-     * a Blueprinter association over an empty `has_many` renders an empty array.
+     * Always present, and `[]` rather than `null` for a link nobody has clicked.
      */
     readonly short_link_clicks: ShortLinkClick[];
     /** The owner rendered inline, or `null` for a link created anonymously. */
@@ -129,7 +118,7 @@ export interface ShortLinkDeviceClicks {
  * `GET /dynamic_qrs/:id/stats` returns.
  *
  * Five keys, always all five. There is no referrer breakdown and no unique
- * visitor count: the backend stores neither.
+ * visitor count: the server stores neither.
  */
 export interface ShortLinkStats {
     readonly total_clicks: number;
@@ -150,8 +139,8 @@ export interface ShortLinkStats {
 /** Arguments for creating a short link. */
 export interface CreateShortLinkInput {
     /**
-     * Absolute destination URL. Must be `http` or `https` and must parse against
-     * `URI::DEFAULT_PARSER`; anything else is a 400, not a silent rewrite.
+     * Absolute destination URL. Must be `http` or `https` and must parse as a
+     * URL; anything else is a 400, not a silent rewrite.
      */
     readonly url: string;
     /**
@@ -169,14 +158,16 @@ export interface UpdateShortLinkInput {
     readonly url?: string;
     readonly endpoint?: string;
 }
+/** Filter columns of `GET /short_links`, on top of {@link BASE_FILTER_COLUMNS}. */
+export declare const SHORT_LINK_FILTER_COLUMNS: readonly ["user_id"];
 /** Filters for {@link ShortLinksNamespace.list}. */
-export interface ListShortLinksParams extends PageParams {
+export interface ListShortLinksParams extends ListParams<(typeof SHORT_LINK_FILTER_COLUMNS)[number]> {
     /**
      * Narrow to one owner, sent as `exact_search[user_id]`.
      *
      * The listing is already scoped to the caller server-side, so this can only
-     * ever narrow your own links to yourself or to nothing. It exists because
-     * the web app sends it; there is no admin escape hatch here.
+     * ever narrow your own links to yourself or to nothing. There is no admin
+     * escape hatch here.
      */
     readonly userId?: Id;
 }
@@ -203,10 +194,10 @@ export declare class ShortLinksNamespace extends Resource {
     /**
      * `POST /short_links` - shortens a URL.
      *
-     * **Rate limit, read this before you spend one:** rack-attack allows
-     * **10 creations per hour per IP** (`short_links_create/ip`), and the rule
-     * is keyed by IP for EVERYONE - being signed in does not buy you a bigger
-     * budget. The 11th call in an hour answers `429` with a `Retry-After` header
+     * **Rate limit, read this before you spend one:** the server allows
+     * **10 creations per hour per IP**, and the rule is keyed by IP for
+     * EVERYONE - being signed in does not buy you a bigger budget. The 11th call
+     * in an hour answers `429` with a `Retry-After` header
      * measured in whatever is left of that hour, which arrives here as an
      * {@link OmsQuotaError} with `retryAfterMs` set. An agent that shortens URLs
      * in a loop will burn the whole hour's budget in about a second, so batch the
@@ -247,7 +238,7 @@ export declare class ShortLinksNamespace extends Resource {
     /**
      * `GET /short_links/:id/stats` - totals plus a fixed 30-day daily histogram.
      *
-     * The window is not configurable: the backend always buckets the last 30
+     * The window is not configurable: the server always buckets the last 30
      * days. For anything else, read {@link ShortLink.short_link_clicks} off the
      * record and bucket it yourself - at the cost noted on that field.
      *
@@ -259,8 +250,8 @@ export declare class ShortLinksNamespace extends Resource {
     /**
      * Finds one of YOUR links by its endpoint, without counting a click.
      *
-     * The public `follow` route records a visit before it redirects, so using it
-     * to read a destination would quietly corrupt the owner's statistics. The
+     * The public redirect records a visit before it redirects, so using it to
+     * read a destination would quietly corrupt the owner's statistics. The
      * API offers no read-by-endpoint, and `search[endpoint]` is not on the
      * allowlist (an unknown filter key is a 400, not a wider result), so the only
      * honest implementation is to page through your own listing and match