instapaper-api 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,452 @@
+/** The subset of `RequestInit` this SDK passes to `fetch`. */
+interface FetchInit {
+    method: string;
+    headers: Record<string, string>;
+    body?: string;
+    signal?: AbortSignal;
+    /** Always `manual`, so credentials are never resent to wherever a redirect points. */
+    redirect: 'manual';
+}
+/** The subset of `Response` this SDK reads. */
+interface FetchResponse {
+    status: number;
+    ok: boolean;
+    text(): Promise<string>;
+}
+/** A `fetch`-compatible function. The global `fetch` satisfies this. */
+type FetchLike = (url: string, init: FetchInit) => Promise<FetchResponse>;
+type QueryValue = string | number | boolean | undefined | null;
+interface TransportOptions {
+    baseUrl?: string;
+    /** Request timeout in milliseconds. `0` disables it. Defaults to 30 seconds. */
+    timeout?: number;
+    /** A custom `fetch`. Defaults to the global one. */
+    fetch?: FetchLike;
+}
+interface SendOptions {
+    query?: Record<string, QueryValue>;
+    headers?: Record<string, string>;
+    body?: string;
+}
+interface RawResponse {
+    status: number;
+    ok: boolean;
+    text: string;
+}
+/** Low-level request plumbing shared by the API client and the OAuth helper. */
+declare class Transport {
+    readonly baseUrl: string;
+    readonly timeout: number;
+    private readonly fetchImpl;
+    constructor(options?: TransportOptions);
+    url(path: string, query?: Record<string, QueryValue>): string;
+    send(method: string, path: string, options?: SendOptions): Promise<RawResponse>;
+}
+interface RequestOptions {
+    query?: Record<string, QueryValue>;
+    json?: unknown;
+    /** Whether a successful response must be a JSON object. `false` for empty-body endpoints. */
+    expectJson?: boolean;
+}
+/** JSON API requests with bearer auth and error mapping. */
+declare class ApiClient {
+    private readonly transport;
+    private readonly accessToken;
+    constructor(transport: Transport, accessToken: string);
+    request<T>(method: string, path: string, options?: RequestOptions): Promise<T>;
+}
+
+/**
+ * Response types for the Instapaper API v2.
+ *
+ * Field names match the JSON the API returns exactly (snake_case), so there is
+ * no mapping layer between what the server sends and what you get back.
+ */
+/** Which list of bookmarks to read. */
+type BookmarkSection = 'home' | 'archive' | 'liked' | 'folder' | 'tag';
+/**
+ * Known values of `Bookmark.category`. New categories may be added, so treat
+ * an unknown value as an article.
+ */
+declare const BookmarkCategory: {
+    readonly Article: 0;
+    readonly Email: 1;
+    readonly Video: 2;
+    readonly PDF: 3;
+    readonly Social: 4;
+};
+type BookmarkCategory = (typeof BookmarkCategory)[keyof typeof BookmarkCategory];
+interface User {
+    /** Stable numeric ID. Store this as your reference to the user. */
+    id: number;
+    /** Usually an email address. Display only; it can change. */
+    username: string;
+    /** Whether the account has an active Instapaper Premium subscription. */
+    premium: boolean;
+}
+interface Tag {
+    id: number;
+    name: string;
+    slug: string;
+    count: number;
+    /** Reserved for Instapaper's own clients; always `null` here. */
+    baton: string | null;
+}
+interface Progress {
+    /** Reading progress from 0.0 to 1.0. */
+    percentage: number;
+    /** When the progress was recorded, as a Unix timestamp. */
+    timestamp: number;
+}
+interface Bookmark {
+    id: number;
+    /** `null` for private content saved without a URL. */
+    url: string | null;
+    title: string | null;
+    description: string | null;
+    image: string | null;
+    progress: Progress;
+    liked: boolean;
+    archived: boolean;
+    /** When the bookmark was saved, as a Unix timestamp. */
+    time: number;
+    /** When the article was published, as a Unix timestamp, if known. */
+    pubtime: number | null;
+    author: string | null;
+    /** The folder it's in, or `null` when it's in the home list. */
+    folder_id: number | null;
+    tags: Tag[];
+    private_source: string | null;
+    /** See {@link BookmarkCategory}. May hold values this SDK doesn't know yet. */
+    category: number;
+}
+interface Folder {
+    id: number;
+    title: string;
+    slug: string;
+    position: number;
+    public: boolean;
+    count: number;
+}
+interface Highlight {
+    id: number;
+    bookmark_id: number;
+    text: string;
+    note: string | null;
+    /** Which occurrence of `text` in the article body this highlight marks, counting from 0. */
+    position: number;
+    /** When it was created, as a Unix timestamp. */
+    time: number;
+}
+interface ArticleAuthor {
+    name: string;
+    url: string | null;
+}
+interface ArticleMetadata {
+    title: string | null;
+    author: ArticleAuthor | null;
+    pubtime: number | null;
+    thumbnail: string | null;
+    description: string | null;
+    private_source: string | null;
+    category: number;
+}
+interface ArticleContent {
+    /** Article HTML, UTF-8, with scripts stripped. */
+    body: string | null;
+    images: string[];
+    words: number | null;
+    paywalled: boolean;
+    /** `ltr` or `rtl`. */
+    direction: string | null;
+}
+interface ParsedArticle {
+    metadata: ArticleMetadata;
+    content: ArticleContent;
+}
+interface BookmarkList {
+    bookmarks: Bookmark[];
+    /** Size of the whole section, not of this page. */
+    total: number;
+}
+interface BookmarkChanges {
+    bookmarks: Bookmark[];
+    /** IDs of bookmarks deleted since the timestamp. */
+    deleted_ids: number[];
+    /** Number of changed bookmarks. */
+    total: number;
+}
+interface TagChanges {
+    /** Tags this call created. */
+    created_tags: Tag[];
+    /** The bookmark's full tag list afterwards. */
+    tags: Tag[];
+}
+/** The user included in a token response. */
+interface TokenUser {
+    id: number;
+    username: string;
+}
+interface AccessToken {
+    access_token: string;
+    token_type: string;
+    user: TokenUser;
+}
+
+interface ListBookmarksOptions {
+    /** Defaults to `home`, or to the section implied by `folderId` or `tag`. */
+    section?: BookmarkSection;
+    folderId?: number;
+    /** Tag name. Can't be combined with `folderId`. */
+    tag?: string;
+    /** 1 to 500. Defaults to 25. */
+    limit?: number;
+    offset?: number;
+}
+interface IterateBookmarksOptions {
+    section?: BookmarkSection;
+    folderId?: number;
+    tag?: string;
+    /** Bookmarks fetched per request, 1 to 500. Defaults to 100. */
+    pageSize?: number;
+}
+interface ChangesOptions {
+    /** 1 to 500. Defaults to 500. */
+    limit?: number;
+    offset?: number;
+}
+interface SyncOptions {
+    /** Changes fetched per request, 1 to 500. Defaults to 500. */
+    pageSize?: number;
+}
+interface SaveBookmarkOptions {
+    /** Required unless `privateSource` is set. */
+    url?: string;
+    /** Send it if you have it; otherwise the title is looked up, which is slower. */
+    title?: string;
+    description?: string;
+    folderId?: number;
+    archived?: boolean;
+    /** `false` skips resolving redirects and canonicalizing the URL. */
+    canonicalize?: boolean;
+    /** Tag names. Tags that don't exist yet are created. */
+    tags?: string[];
+    /** Full article HTML, if you already have it. Required with `privateSource`. */
+    content?: string;
+    /** A short label naming where private content came from. Used instead of `url`. */
+    privateSource?: string;
+}
+interface UpdateBookmarkOptions {
+    title?: string;
+    description?: string;
+    /** Reading progress from 0.0 to 1.0. */
+    progress?: number;
+    /** When the progress was recorded, as a Unix timestamp. Defaults to now. */
+    progressTimestamp?: number;
+}
+interface UpdateTagsOptions {
+    /** Tag names (created if needed) or tag IDs to add. */
+    add?: Array<string | number>;
+    /** Tag IDs to remove. */
+    remove?: number[];
+}
+interface ParseOptions {
+    /** `false` bypasses the parser cache. Defaults to `true`. */
+    useCache?: boolean;
+    /** Force a re-parse rather than serving a stored copy. Defaults to `false`. */
+    force?: boolean;
+    /** HTML you already have for the article, parsed instead of fetching the URL. */
+    content?: string;
+    /** Your Instaparser key, required for non-personal use. */
+    instaparserApiKey?: string;
+}
+/** List, save, update, move, like, tag, delete, and parse bookmarks. */
+declare class Bookmarks {
+    private readonly api;
+    constructor(api: ApiClient);
+    /** One page of bookmarks from a section. */
+    list(options?: ListBookmarksOptions): Promise<BookmarkList>;
+    /** Every bookmark in a section, fetching pages as you go. */
+    iterate(options?: IterateBookmarksOptions): AsyncIterableIterator<Bookmark>;
+    /** One page of bookmarks changed since a time, across every section, plus deleted IDs. */
+    changes(since: number | Date, options?: ChangesOptions): Promise<BookmarkChanges>;
+    /**
+     * Everything changed since a time, fetching every page. Record when you
+     * started the sync and pass it as `since` next time.
+     */
+    sync(since: number | Date, options?: SyncOptions): Promise<BookmarkChanges>;
+    /** Save a URL, or private content. Saving a URL twice updates the existing bookmark. */
+    save(options: SaveBookmarkOptions): Promise<Bookmark>;
+    /** Change a bookmark's title, description, or reading progress. */
+    update(bookmarkId: number, options: UpdateBookmarkOptions): Promise<Bookmark>;
+    /** Permanently delete a bookmark. This is not the same as archiving. */
+    delete(bookmarkId: number): Promise<void>;
+    archive(bookmarkId: number): Promise<Bookmark>;
+    /** Move a bookmark back to the home list. */
+    unarchive(bookmarkId: number): Promise<Bookmark>;
+    moveToFolder(bookmarkId: number, folderId: number): Promise<Bookmark>;
+    like(bookmarkId: number): Promise<Bookmark>;
+    unlike(bookmarkId: number): Promise<Bookmark>;
+    /** Add tags (by name or ID) to a bookmark and remove tags (by ID) from it. */
+    updateTags(bookmarkId: number, options: UpdateTagsOptions): Promise<TagChanges>;
+    /** Instapaper's parsed, reader-ready version of a saved article. */
+    parse(bookmarkId: number, options?: ParseOptions): Promise<ParsedArticle>;
+    private move;
+}
+
+interface FolderPosition {
+    folderId: number;
+    position: number;
+}
+/** List, create, reorder, and delete a user's folders. */
+declare class Folders {
+    private readonly api;
+    constructor(api: ApiClient);
+    /** The user's folders, in their own order. */
+    list(): Promise<Folder[]>;
+    create(title: string): Promise<Folder>;
+    /** Delete a folder. Its bookmarks move back to the home list. */
+    delete(folderId: number): Promise<void>;
+    /**
+     * Set folder positions, as a `{ folderId: position }` map or a list. Folders
+     * you leave out keep their positions. Returns every folder in its new order.
+     */
+    reorder(positions: Record<number, number> | FolderPosition[]): Promise<Folder[]>;
+}
+
+interface CreateHighlightOptions {
+    /** The highlighted text. Leading and trailing whitespace is trimmed by the API. */
+    text: string;
+    note?: string;
+    /**
+     * Which occurrence of `text` in the article body to highlight, counting
+     * from 0. Defaults to 0, the first occurrence.
+     */
+    position?: number;
+}
+/** Read, create, and delete highlights on a bookmark. */
+declare class Highlights {
+    private readonly api;
+    constructor(api: ApiClient);
+    list(bookmarkId: number): Promise<Highlight[]>;
+    /**
+     * Create a highlight. Accounts without Premium can create five per month;
+     * past that this throws a `PermissionDeniedError`.
+     */
+    create(bookmarkId: number, options: CreateHighlightOptions): Promise<Highlight>;
+    /**
+     * Delete a highlight. Throws `BadRequestError` if the highlight doesn't
+     * exist, belongs to someone else, or was already deleted.
+     */
+    delete(highlightId: number): Promise<void>;
+}
+
+/** List, create, and rename a user's tags. */
+declare class Tags {
+    private readonly api;
+    constructor(api: ApiClient);
+    list(): Promise<Tag[]>;
+    create(name: string): Promise<Tag>;
+    rename(tagId: number, name: string): Promise<Tag>;
+}
+
+interface InstapaperOptions extends TransportOptions {
+    /** A personal access token, or one issued through the OAuth flow. */
+    accessToken: string;
+}
+/** Client for the Instapaper API v2. */
+declare class Instapaper {
+    readonly bookmarks: Bookmarks;
+    readonly folders: Folders;
+    readonly tags: Tags;
+    readonly highlights: Highlights;
+    private readonly api;
+    constructor(options: InstapaperOptions);
+    /** The account the access token belongs to. */
+    me(): Promise<User>;
+}
+
+interface OAuthOptions extends TransportOptions {
+    clientId: string;
+    clientSecret: string;
+    /** Must match one of the application's registered callback URIs exactly. */
+    redirectUri: string;
+}
+interface AuthorizationUrlOptions {
+    /** An opaque value echoed back to your redirect URI. Use it to defend against CSRF. */
+    state?: string;
+}
+/** Helpers for the OAuth 2 authorization code flow. */
+declare class OAuth {
+    readonly clientId: string;
+    readonly redirectUri: string;
+    private readonly clientSecret;
+    private readonly transport;
+    constructor(options: OAuthOptions);
+    /** The URL to send the user to so they can authorize your application. */
+    authorizationUrl(options?: AuthorizationUrlOptions): string;
+    /** Exchange the code from your redirect URI for an access token. Codes work once. */
+    exchangeCode(code: string): Promise<AccessToken>;
+}
+
+/** Base class for every error this SDK throws. */
+declare class InstapaperError extends Error {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** The API answered with an error status. */
+declare class APIError extends InstapaperError {
+    /** HTTP status code. */
+    readonly status: number;
+    /** The parsed JSON body, the raw text if it wasn't JSON, or `undefined` if empty. */
+    readonly body: unknown;
+    constructor(message: string, status: number, body?: unknown);
+}
+/** 400: the request was malformed, or an argument was missing or invalid. */
+declare class BadRequestError extends APIError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+/** 401: the access token is missing, unknown, or revoked. */
+declare class AuthenticationError extends APIError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+/** 402: an external content quota is exhausted (e.g. Instaparser credits). */
+declare class QuotaExceededError extends APIError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+/** 403: authenticated, but not allowed (unapproved or suspended app, or a Premium feature). */
+declare class PermissionDeniedError extends APIError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+/** 404: no such endpoint. */
+declare class NotFoundError extends APIError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+/** 429: rate limited. Back off and retry later. */
+declare class RateLimitError extends APIError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+/** 5xx: something went wrong on Instapaper's side. Retry with backoff. */
+declare class ServerError extends APIError {
+    constructor(message: string, status?: number, body?: unknown);
+}
+/** The OAuth token endpoint rejected a request (RFC 6749 error response). */
+declare class OAuthError extends InstapaperError {
+    readonly status: number;
+    /** The OAuth error code, e.g. `invalid_grant`. */
+    readonly error: string;
+    readonly description: string;
+    constructor(status: number, error: string, description: string);
+}
+/** The request never got a response: a network failure or a timeout. */
+declare class InstapaperConnectionError extends InstapaperError {
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+
+/** The SDK version, sent in the User-Agent header where the runtime allows it. */
+declare const VERSION = "0.1.0";
+
+export { APIError, type AccessToken, type ArticleAuthor, type ArticleContent, type ArticleMetadata, AuthenticationError, type AuthorizationUrlOptions, BadRequestError, type Bookmark, BookmarkCategory, type BookmarkChanges, type BookmarkList, type BookmarkSection, Bookmarks, type ChangesOptions, type CreateHighlightOptions, type FetchInit, type FetchLike, type FetchResponse, type Folder, type FolderPosition, Folders, type Highlight, Highlights, Instapaper, InstapaperConnectionError, InstapaperError, type InstapaperOptions, type IterateBookmarksOptions, type ListBookmarksOptions, NotFoundError, OAuth, OAuthError, type OAuthOptions, type ParseOptions, type ParsedArticle, PermissionDeniedError, type Progress, QuotaExceededError, RateLimitError, type SaveBookmarkOptions, ServerError, type SyncOptions, type Tag, type TagChanges, Tags, type TokenUser, type UpdateBookmarkOptions, type UpdateTagsOptions, type User, VERSION };