teak-sdk 1.0.86 → 1.0.88

package/types/index.d.ts

@@ -0,0 +1,569 @@
+export { formatBytes } from "./convex/shared/utils/formatBytes.js";
+export { type AuthDiscovery, discoverAuthServer, type OAuthSurface, validateOAuthUrl, } from "./authDiscovery.js";
+export { type CredentialBinding, isRefreshTokenDead, isWorkosCredential, matchesBinding, refreshAndSave, } from "./oauthCredentials.js";
+export { type ConnectTokenResult, type ConnectTokens, createConnectAuthorizeUrl, createPkceChallenge, disconnectConnectGrant, fetchConnectOwnerId, randomBase64Url, requestConnectTokens, WORKOS_CONNECT_SCOPE, } from "./workosConnect.js";
+import { type CardType } from "./convex/shared/constants.js";
+import type { FileKind, FilePreviewFacts } from "./convex/shared/fileFormats.js";
+import type { FOLDER_COLORS } from "./convex/shared/folders.js";
+export type { CardType } from "./convex/shared/constants.js";
+export declare const CARD_TYPES: readonly ["text", "link", "image", "video", "audio", "document", "palette", "quote"];
+export declare const CARD_SORTS: readonly ["newest", "oldest", "relevance", "shuffle"];
+export declare const ERROR_CODES: readonly ["AUTH_REQUIRED", "BAD_REQUEST", "CARD_LIMIT_REACHED", "CONFIG_ERROR", "CONFLICT", "CONTENT_TOO_LARGE", "FILE_TOO_LARGE", "FOLDER_LIMIT", "FORBIDDEN", "IN_PROGRESS", "INTERNAL_ERROR", "INVALID_API_KEY", "INVALID_INPUT", "INVALID_STORAGE_KEY", "INVALID_UTF8", "LIMIT_REACHED", "METHOD_NOT_ALLOWED", "NETWORK_ERROR", "NOT_FOUND", "NO_CONTENT", "NOT_IN_TRASH", "PARSE_ERROR", "RATE_LIMITED", "REQUEST_FAILED", "SERVICE_UNAVAILABLE", "SMART_FOLDER", "TAG_EXISTS", "TAG_OPERATION_RUNNING", "TIMEOUT", "TYPE_MISMATCH", "UNAUTHORIZED", "UNSUPPORTED_TYPE"];
+export type CardSort = (typeof CARD_SORTS)[number];
+/**
+ * How a search finds cards: `hybrid` (the API's default) matches words and
+ * meaning, `keyword` words only, `semantic` meaning only.
+ */
+export type SearchMode = "hybrid" | "keyword" | "semantic";
+export type TeakApiErrorCode = (typeof ERROR_CODES)[number];
+export type FetchLike = typeof fetch;
+export interface TokenProvider {
+    getAccessToken: () => Promise<string | null> | string | null;
+    onUnauthorized?: (rejectedToken: string) => Promise<string | null> | string | null;
+}
+export interface Card {
+    aiSummary: string | null;
+    aiTags: string[];
+    aiTranscript: string | null;
+    appUrl: string;
+    /** When the card was archived, or null. */
+    archivedAt: number | null;
+    /** Bar heights 0-100: 45 for a grid card, 200 for a player. */
+    audioWaveform: {
+        detail: number[];
+        grid: number[];
+    } | null;
+    /** Your cards that link to this one, most recently updated first. */
+    backlinks?: CardLinkRef[];
+    backlinksTruncated?: boolean;
+    colors: Array<{
+        hex: string;
+        name?: string;
+    }>;
+    compactUrl: string | null;
+    /**
+     * When the link was marked read, watched, bought or done, or null.
+     * Servers that predate done states leave it out.
+     */
+    completedAt?: number | null;
+    content: string;
+    createdAt: number;
+    detailUrl: string | null;
+    fileExtension: string | null;
+    fileKind: FileKind | null;
+    fileLanguage: string | null;
+    fileName: string | null;
+    filePreview: FilePreviewFacts | null;
+    fileSize: number | null;
+    fileUrl: string | null;
+    /** Ids of the folders the card is in. */
+    folderIds: string[];
+    id: string;
+    /** Archived cards are hidden from the library but still count. */
+    isArchived: boolean;
+    isDeleted: boolean;
+    isFavorited: boolean;
+    /**
+     * Tagged `secret` or `hidden`: left out of lists and searches unless the
+     * search names one of those tags (`#secret`). Servers that
+     * predate hidden cards leave it out.
+     */
+    isHidden?: boolean;
+    linkAuthor: string | null;
+    /**
+     * What a link is (`article`, `movie`, `product`…), or null. A plain
+     * string: new categories are added over time.
+     */
+    linkCategory?: string | null;
+    linkFacts: Array<{
+        label: string;
+        value: string;
+    }>;
+    linkPreviewImageUrl: string | null;
+    linkPreviewMedia: Array<{
+        type: "image" | "video";
+        url: string;
+        contentType?: string;
+        width?: number;
+        height?: number;
+        posterUrl?: string;
+        posterContentType?: string;
+        posterWidth?: number;
+        posterHeight?: number;
+    }>;
+    /**
+     * A product link's price: `amount` in the page's currency, `currency` an
+     * ISO 4217 code or null. Null for cards without a price.
+     */
+    linkPrice: {
+        amount: number;
+        currency: string | null;
+    } | null;
+    linkPublishedAt: string | null;
+    linkPublisher: string | null;
+    linkSiteName: string | null;
+    /**
+     * Cards this card links to with `[[Title|teak:<id>]]`, in order. Only on
+     * single-card responses (`cards.get`, update, favorite, done, create).
+     */
+    links?: CardLinkRef[];
+    linksTruncated?: boolean;
+    metadataDescription: string | null;
+    metadataStatus: string | null;
+    metadataTitle: string | null;
+    mimeType: string | null;
+    notes: string | null;
+    placeholderUrl: string | null;
+    processingStatus: Record<string, unknown> | null;
+    screenshotUrl: string | null;
+    /**
+     * The title of the page in `sourceUrl`. Servers that predate sources
+     * leave it out.
+     */
+    sourceTitle?: string | null;
+    /**
+     * The page the card was saved from, such as the page a quote was selected
+     * on. Servers that predate sources leave it out.
+     */
+    sourceUrl?: string | null;
+    tags: string[];
+    /** True when linkPreviewImageUrl is an image chosen for the link. */
+    thumbnailOverridden: boolean;
+    thumbnailUrl: string | null;
+    type: CardType | string;
+    updatedAt: number;
+    url: string | null;
+    /** Hover preview strip, `frames * frameWidth` wide; the URL expires. */
+    videoScrub: {
+        frameHeight: number;
+        frameWidth: number;
+        frames: number;
+        url: string;
+    } | null;
+}
+/** A linked card; `missing` when it's in Trash, deleted or not yours. */
+export interface CardLinkRef {
+    id: string;
+    missing: boolean;
+    title: string | null;
+    type: CardType | string | null;
+}
+export interface CardLinks {
+    backlinks: CardLinkRef[];
+    backlinksTruncated: boolean;
+    links: CardLinkRef[];
+    linksTruncated: boolean;
+}
+export type CardListItem = Partial<Card> & Pick<Card, "aiTags" | "appUrl" | "createdAt" | "id" | "isFavorited" | "tags" | "type" | "updatedAt">;
+export interface PageInfo {
+    hasMore: boolean;
+    nextCursor: string | null;
+}
+export interface CardsPage {
+    items: CardListItem[];
+    pageInfo: PageInfo;
+    /** With a query and `sort: "relevance"`: whether the top results were scored. */
+    relevanceRanked?: boolean;
+    /** With a query: the mode that ran (`keyword` when meaning search could not). */
+    searchMode?: SearchMode;
+    /**
+     * For similar cards: `pending` while the card is still being read, and
+     * `unavailable` for a card in Trash or not found.
+     */
+    similarity?: "ok" | "pending" | "unavailable";
+}
+export interface CardChangesResponse {
+    deletedIds: string[];
+    items: Card[];
+    pageInfo: PageInfo;
+}
+export interface TagSummary {
+    count: number;
+    name: string;
+}
+export type FolderColor = (typeof FOLDER_COLORS)[number];
+export interface Folder {
+    /**
+     * Cards in a manual folder that are not archived or in Trash; null for a
+     * smart folder, whose cards are found when listed.
+     */
+    cardCount: number | null;
+    color: FolderColor | null;
+    createdAt: number;
+    id: string;
+    /** Manual folders hold the cards put in them; smart ones save a search. */
+    kind: "manual" | "smart";
+    name: string;
+    /** A smart folder's search; null for a manual folder. */
+    query: string | null;
+    updatedAt: number;
+}
+export type TagOperationKind = "rename" | "merge" | "delete";
+export type TagOperationStatus = "running" | "completed" | "failed";
+/** A library-wide tag rename, merge or delete, finished in the background. */
+export interface TagOperation {
+    /** Cards rewritten so far. */
+    changed: number;
+    completedAt: number | null;
+    createdAt: number;
+    error: string | null;
+    /** The tag being changed, lowercased. */
+    from: string;
+    id: string;
+    kind: TagOperationKind;
+    /** Cards looked at so far. */
+    processed: number;
+    status: TagOperationStatus;
+    /** The new name (rename) or the tag merged into (merge). */
+    to: string | null;
+    /** Cards carrying the tag when the change started. */
+    total: number;
+    updatedAt: number;
+}
+export interface FolderCardsResult {
+    failedIds: string[];
+    /** Failed cards that are already in the most folders a card can be in. */
+    folderLimitIds: string[];
+    updatedIds: string[];
+}
+export interface CreateCardInput {
+    /**
+     * Optional card type: `text`, `link`, `image`, `video`, `audio`,
+     * `document`, `palette` or `quote`. Set it to `text` to store raw Markdown
+     * exactly; omit it to keep automatic URL, quote, and palette detection.
+     * @default inferred
+     */
+    cardType?: CardType;
+    /**
+     * Markdown or plain text body for the card. Prefer this for notes; use `url`
+     * when saving a link.
+     */
+    content?: string;
+    /** The `ETag` the upload `PUT` returned, for a file card. */
+    fileEtag?: string;
+    /** The `fileKey` from `uploads.create`, for a file card. */
+    fileKey?: string;
+    /** The uploaded file's name, for a file card. */
+    fileName?: string;
+    /** The uploaded file's size in bytes, for a file card. */
+    fileSize?: number;
+    /** The uploaded file's MIME type, for a file card. */
+    mimeType?: string;
+    /** Free-form notes attached to the card. */
+    notes?: string | null;
+    /**
+     * A free label for what saved the card (extension, CLI, API, and so on),
+     * kept in its metadata. For the page the card came from, use `sourceUrl`.
+     */
+    source?: string;
+    /** The page's title, beside `sourceUrl`; cut to 300 characters. */
+    sourceTitle?: string;
+    /**
+     * The page the card came from, such as the page a quote was selected on:
+     * an http or https URL of at most 2,048 characters. Unlike `url`, it never
+     * makes the card a link.
+     */
+    sourceUrl?: string;
+    /** Tags to apply on create. */
+    tags?: string[];
+    /**
+     * URL to save as a link card. Teak may classify the type automatically when
+     * `cardType` is omitted.
+     */
+    url?: string;
+}
+export interface UpdateCardInput {
+    content?: string;
+    /** Replaces the card's folders; an empty list takes it out of every folder. */
+    folderIds?: string[];
+    isArchived?: boolean;
+    metadataTitle?: string | null;
+    notes?: string | null;
+    /** AI tags to drop. `tags` replaces only the card's own tags. */
+    removeAiTags?: string[];
+    tags?: string[];
+    url?: string;
+}
+export interface Me {
+    cardCount: number;
+    /** Null on Pro, which has no card limit. */
+    cardLimit: number | null;
+    email: string;
+    id: string;
+    name?: string;
+    plan: "free" | "pro";
+    settingsUrl: string;
+}
+export interface ExportJob {
+    cardCount: number | null;
+    completedAt: number | null;
+    createdAt: number;
+    downloadUrl: string | null;
+    expiresAt: number | null;
+    failureClass: string | null;
+    filesIncluded: number | null;
+    filesOmitted: number | null;
+    id: string;
+    processedCount: number | null;
+    sizeBytes: number | null;
+    stage: "snapshotting" | "archiving" | null;
+    status: "pending" | "running" | "ready" | "failed" | "canceled" | "expired";
+    updatedAt: number;
+}
+export interface LatestExport {
+    canStartNew: boolean;
+    job: ExportJob | null;
+    nextAvailableAt: number | null;
+}
+export interface RequestOptions {
+    /** Makes a retried create or bulk request safe to repeat. */
+    idempotencyKey?: string;
+}
+export interface CreateUploadInput {
+    fileName: string;
+    fileSize: number;
+    mimeType: string;
+}
+/** A link image upload: JPEG, PNG, WebP, GIF or AVIF, under 20 MB. */
+export interface CreateThumbnailUploadInput {
+    fileSize: number;
+    mimeType: string;
+}
+export interface CreateUploadResponse {
+    expiresIn: number;
+    fileKey: string;
+    maxFileSize: number;
+    method: "PUT";
+    uploadUrl: string;
+}
+export interface CreateCardResponse {
+    appUrl: string;
+    card?: Card;
+    cardId: string;
+    status: "created";
+}
+export interface RefreshCardResponse {
+    cardId: string;
+    requestedAt: number;
+    status: "queued";
+}
+/** An arXiv link's PDF saved as a document card (POST /v1/cards/:id/save-pdf). */
+export interface SavedPdf {
+    /** The document card holding the PDF. */
+    cardId: string;
+    /** False when an earlier save already made that card. */
+    created: boolean;
+}
+/** A card's full stored text (GET /v1/cards/:id/content). */
+export interface CardContent {
+    cardId: string;
+    /** Characters in the full stored text. */
+    charCount: number;
+    /**
+     * document: extracted from the card's file; transcript: its speech;
+     * content: a text or quote card's written text.
+     */
+    kind: "document" | "transcript" | "content";
+    text: string;
+    /** The document is longer than Teak keeps. */
+    truncated: boolean;
+}
+export type BulkCardsOperation = "create" | "update" | "favorite" | "delete" | "archive" | "unarchive" | "addTags" | "removeTags" | "restore";
+export interface BulkCardsResponse {
+    /** The `cardId` of every item that failed, to retry just those. */
+    failedIds: string[];
+    operation: BulkCardsOperation;
+    results: unknown[];
+    summary: {
+        failed: number;
+        succeeded: number;
+        total: number;
+    };
+}
+/** Archived cards outside Trash: left out by default. */
+export type ArchivedFilter = "exclude" | "only" | "include";
+export declare class TeakApiError extends Error {
+    code: TeakApiErrorCode;
+    requestId?: string;
+    retryAt?: number;
+    status?: number;
+    constructor(code: TeakApiErrorCode, message?: string, init?: {
+        requestId?: string;
+        retryAt?: number;
+        status?: number;
+    });
+}
+export declare const staticTokenProvider: (token: string) => TokenProvider;
+export declare const normalizeLimit: (limit?: number) => number;
+export declare const buildCardsSearchParams: (input: {
+    archived?: ArchivedFilter;
+    /** Only cards in this folder id. */
+    folder?: string;
+    createdAfter?: number;
+    createdBefore?: number;
+    cursor?: string;
+    favorited?: boolean;
+    hex?: string | readonly string[];
+    hue?: string | readonly string[];
+    include?: string;
+    limit?: number;
+    /** How `query` finds cards; the API defaults to `hybrid`. */
+    mode?: SearchMode;
+    /**
+     * Search text. Accepts qualifiers: `tag:design` or `#design`, `type:link`,
+     * `is:fav`, `is:archived`, `site:github.com`, `folder:"Reading list"`,
+     * `price:<100` (also `>`, `<=`, `>=` and `=`), `text:"total due"` (only
+     * the words Teak read in images, video thumbnails, link previews and scanned
+     * PDFs) and `"quoted phrases"`.
+     */
+    query?: string;
+    /** Required with `sort: "shuffle"`: the same seed gives the same order. */
+    shuffleSeed?: number;
+    /** A card id: only the cards closest to it in meaning. */
+    similarTo?: string;
+    sort?: CardSort;
+    style?: string | readonly string[];
+    tag?: string;
+    trashed?: boolean;
+    type?: CardType | string | readonly (CardType | string)[];
+}) => string;
+export declare const createTeakClient: (options: {
+    baseUrl?: string;
+    fetch?: FetchLike;
+    timeoutMs?: number;
+    tokenProvider: TokenProvider;
+    userAgent?: string;
+}) => {
+    cards: {
+        bulk: (operation: BulkCardsOperation, items: unknown[], requestOptions?: RequestOptions) => Promise<BulkCardsResponse>;
+        changes: (input: {
+            cursor?: string;
+            limit?: number;
+            since: number;
+        }) => Promise<CardChangesResponse>;
+        create: (input: CreateCardInput, requestOptions?: RequestOptions) => Promise<CreateCardResponse>;
+        /**
+         * The card's full stored text: document text, transcript, or a text
+         * card's content. Throws NO_CONTENT when the card has none.
+         */
+        content: (id: string) => Promise<CardContent>;
+        /** Moves the card to Trash, or deletes it for good with `permanent`. */
+        delete: (id: string, deleteOptions?: {
+            permanent?: boolean;
+        }) => Promise<null>;
+        /** The ID of a saved card with exactly this URL, or null. */
+        duplicate: (url: string) => Promise<string | null>;
+        favorites: (input?: Parameters<(params: Parameters<typeof buildCardsSearchParams>[0]) => string>[0]) => Promise<CardsPage>;
+        get: (id: string) => Promise<Card>;
+        /** Cards this card links to with `[[…]]`, and cards linking to it. */
+        links: (id: string) => Promise<CardLinks>;
+        list: (input?: Parameters<(params: Parameters<typeof buildCardsSearchParams>[0]) => string>[0]) => Promise<CardsPage>;
+        /**
+         * A signed URL for a link card's new image; `setThumbnail` with bytes
+         * does this for you.
+         */
+        createThumbnailUpload: (id: string, input: CreateThumbnailUploadInput) => Promise<CreateUploadResponse>;
+        /** Refreshes summary, tags and link preview; it finishes in the background. */
+        refresh: (id: string) => Promise<RefreshCardResponse>;
+        /**
+         * Goes back to the image Teak found for a link card and deletes the one
+         * that replaced it. Changes nothing when the card has its own image.
+         */
+        resetThumbnail: (id: string) => Promise<Card>;
+        restore: (id: string) => Promise<null>;
+        /** The cards closest in meaning to one card; never the card itself. */
+        similar: (id: string, input?: Parameters<(params: Parameters<typeof buildCardsSearchParams>[0]) => string>[0]) => Promise<CardsPage>;
+        search: (input?: Parameters<(params: Parameters<typeof buildCardsSearchParams>[0]) => string>[0]) => Promise<CardsPage>;
+        /** Archives the card (hidden from the library, not deleted) or returns it. */
+        setArchived: (id: string, isArchived: boolean) => Promise<Card>;
+        /**
+         * Replaces a link card's image: uploads `bytes` (JPEG, PNG, WebP, GIF or
+         * AVIF, under 20 MB) and applies them. Pass `{ fileKey }` instead to
+         * apply an upload made with `createThumbnailUpload`.
+         */
+        setThumbnail: (id: string, image: BodyInit | {
+            fileKey: string;
+        }, mimeType?: string) => Promise<Card>;
+        /**
+         * Saves an arXiv link's paper as its own document card. Saving the same
+         * link again returns that card with `created: false`.
+         */
+        savePdf: (id: string) => Promise<SavedPdf>;
+        /**
+         * Marks a link card read, watched, bought or done (`done: true`), or
+         * not; repeating a call changes nothing. Only link cards can be marked.
+         */
+        setDone: (id: string, done: boolean) => Promise<Card>;
+        setFavorite: (id: string, isFavorited: boolean) => Promise<Card>;
+        update: (id: string, input: UpdateCardInput) => Promise<Card>;
+    };
+    exports: {
+        latest: () => Promise<LatestExport>;
+        start: () => Promise<ExportJob>;
+    };
+    folders: {
+        /**
+         * Adds up to 100 cards; cards already in the folder are left as they
+         * are. A smart folder refuses cards (409 SMART_FOLDER).
+         */
+        addCards: (id: string, cardIds: string[]) => Promise<FolderCardsResult>;
+        /**
+         * Creates a folder; `{ kind: "smart", query }` saves a search, whose
+         * cards are whatever matches it when listed.
+         */
+        create: (input: {
+            color?: FolderColor;
+            kind?: "manual";
+            name: string;
+        } | {
+            color?: FolderColor;
+            kind: "smart";
+            name: string;
+            query: string;
+        }) => Promise<Folder>;
+        /** Deletes the folder; its cards are kept. */
+        delete: (id: string) => Promise<null>;
+        get: (id: string) => Promise<Folder>;
+        /** Every folder, sorted by name. */
+        list: () => Promise<{
+            items: Folder[];
+        }>;
+        removeCards: (id: string, cardIds: string[]) => Promise<FolderCardsResult>;
+        /**
+         * Renames or recolors; `color: null` clears the color. `query` changes
+         * a smart folder's search.
+         */
+        update: (id: string, input: {
+            color?: FolderColor | null;
+            name?: string;
+            query?: string;
+        }) => Promise<Folder>;
+    };
+    me: () => Promise<Me>;
+    tags: {
+        /**
+         * Deletes a tag from every card, including cards in Trash and Archive.
+         * It finishes in the background; poll with `operation`.
+         */
+        delete: (tag: string) => Promise<TagOperation>;
+        list: () => Promise<{
+            items: TagSummary[];
+        }>;
+        /** Replaces `from` with `into` on every card; it finishes in the background. */
+        merge: (from: string, into: string) => Promise<TagOperation>;
+        /** A tag change's progress. */
+        operation: (id: string) => Promise<TagOperation>;
+        /** Renames a tag on every card; it finishes in the background. */
+        rename: (from: string, to: string) => Promise<TagOperation>;
+    };
+    uploads: {
+        create: (input: CreateUploadInput) => Promise<CreateUploadResponse>;
+        putFile: (uploadUrl: string, bytes: BodyInit, mimeType: string) => Promise<{
+            fileEtag: string | undefined;
+        }>;
+    };
+};
+export type TeakClient = ReturnType<typeof createTeakClient>;
+export declare const parseTags: (value: string | undefined) => string[] | undefined;
+export declare const isCardType: (value: string) => value is CardType;
+export declare const isStringList: (value: unknown) => value is string[];

package/types/oauthCredentials.d.ts

@@ -0,0 +1,10 @@
+import type { ConnectTokenResult } from "./workosConnect.js";
+export interface CredentialBinding {
+    clientId: string;
+    issuer: string;
+    origin: string;
+}
+export declare const isWorkosCredential: (saved: Partial<CredentialBinding> | undefined) => saved is CredentialBinding;
+export declare const matchesBinding: (saved: Partial<CredentialBinding> | undefined, current: CredentialBinding) => boolean;
+export declare const isRefreshTokenDead: (result: ConnectTokenResult) => boolean;
+export declare const refreshAndSave: <T>(refresh: () => Promise<T>, save: (renewed: NonNullable<T>) => unknown) => Promise<T>;