teak-sdk 1.0.89 → 1.0.91

package/README.md

@@ -1,30 +1,23 @@
 # Teak SDK
 
-Typed API client and OAuth discovery for Teak. The source lives in `src/`, and
-`bun run build` writes the npm package to `dist/`: one bundle with no runtime
-dependencies, so it works without the Teak monorepo.
+Typed API client and OAuth discovery for [Teak](https://teakvault.com). One
+bundle with no runtime dependencies.
+
+```bash
+npm i teak-sdk
+```
 
 ```ts
-import { createTeakClient, discoverAuthServer } from "teak-sdk";
+import { createTeakClient, staticTokenProvider } from "teak-sdk";
 
-const auth = await discoverAuthServer("https://teakvault.com/api");
 const client = createTeakClient({
   baseUrl: "https://teakvault.com/api",
-  tokenProvider: { getAccessToken: () => yourStoredAccessToken },
+  tokenProvider: staticTokenProvider(process.env.TEAK_API_KEY!),
 });
-```
 
-Use the discovered endpoints and client ID for your OAuth surface. The WorkOS
-Connect helpers (`createPkceChallenge`, `createConnectAuthorizeUrl`,
-`requestConnectTokens`, `fetchConnectOwnerId`, `disconnectConnectGrant`) cover
-PKCE sign-in, refresh, account binding and disconnect. Refresh
-discovery after sign-in or refresh failures. Keep tokens in your platform's secure
-storage; this package does not store credentials or open a browser.
-
-The optional `TokenProvider.onUnauthorized(rejectedToken: string)` callback receives
-the token used by a retry-eligible 401 response. Return a new or already-refreshed
-token to retry once, or `null` to stop. Check the rejected token against the current
-session before refreshing so an older response cannot invalidate newer credentials.
+await client.cards.create({ content: "A note from my script" });
+```
 
-Install it from npm as `teak-sdk`. Each release shares the lockstep version of
-the other Teak products and is published by the `SDK Release` workflow.
+The guide, with token providers and WorkOS Connect sign-in, is at
+[teakvault.com/docs/sdk](https://teakvault.com/docs/sdk). Each release shares
+the lockstep version of the other Teak products.

package/index.js

@@ -335,7 +335,6 @@ var fetchConnectOwnerId = async (apiUrl, accessToken, options = {}) => {
 };
 // ../convex/shared/markdown.ts
 var MARKDOWN_CONTENT_MAX_BYTES = 512 * 1024;
-
 // ../files-protocol/src/decisions.ts
 var CLEF_MODEL_ID = "@cf/cloudflare/clef";
 var CLEF_FLASH_MODEL_ID = "@cf/cloudflare/clef-flash";
@@ -978,6 +977,7 @@ var ERROR_CODES = [
   "FILE_TOO_LARGE",
   "FOLDER_LIMIT",
   "FORBIDDEN",
+  "HIGHLIGHT_LIMIT",
   "IN_PROGRESS",
   "INTERNAL_ERROR",
   "INVALID_API_KEY",
@@ -988,9 +988,12 @@ var ERROR_CODES = [
   "METHOD_NOT_ALLOWED",
   "NETWORK_ERROR",
   "NOT_FOUND",
+  "NO_ARTICLE",
   "NO_CONTENT",
   "NOT_IN_TRASH",
+  "PAGE_SNAPSHOT_TOO_LARGE",
   "PARSE_ERROR",
+  "QUOTE_NOT_FOUND",
   "RATE_LIMITED",
   "REQUEST_FAILED",
   "SERVICE_UNAVAILABLE",
@@ -1188,6 +1191,18 @@ var asFolders = (value) => {
   }
   return { items: value.items.map(asFolder) };
 };
+var asHighlight = (value) => {
+  if (!isObject(value) || typeof value.id !== "string" || typeof value.quote !== "string") {
+    throw new TeakApiError("PARSE_ERROR", "Teak returned an unexpected highlight payload.");
+  }
+  return value;
+};
+var asHighlights = (value) => {
+  if (!(isObject(value) && Array.isArray(value.items))) {
+    throw new TeakApiError("PARSE_ERROR");
+  }
+  return { items: value.items.map(asHighlight) };
+};
 var asFolderCards = (value) => {
   if (!(isObject(value) && isStringArray(value.updatedIds) && isStringArray(value.failedIds))) {
     throw new TeakApiError("PARSE_ERROR");
@@ -1235,7 +1250,7 @@ var asSavedPdf = (value) => {
   return { cardId: value.cardId, created: value.created };
 };
 var asCardContent = (value) => {
-  if (!isObject(value) || typeof value.cardId !== "string" || typeof value.text !== "string" || typeof value.charCount !== "number" || typeof value.truncated !== "boolean" || !["document", "transcript", "content"].includes(String(value.kind))) {
+  if (!isObject(value) || typeof value.cardId !== "string" || typeof value.text !== "string" || typeof value.charCount !== "number" || typeof value.truncated !== "boolean" || typeof value.kind !== "string") {
     throw new TeakApiError("PARSE_ERROR");
   }
   return value;
@@ -1319,6 +1334,7 @@ var createTeakClient = (options) => {
   const idempotency = (requestOptions) => requestOptions?.idempotencyKey ? { "Idempotency-Key": requestOptions.idempotencyKey } : {};
   const cardPath = (id) => `/v1/cards/${encodeURIComponent(id)}`;
   const folderPath = (id) => `/v1/folders/${encodeURIComponent(id)}`;
+  const highlightPath = (id) => `/v1/highlights/${encodeURIComponent(id)}`;
   const putFile = async (uploadUrl, bytes, mimeType) => {
     const headers = new Headers({ "Content-Type": mimeType });
     const byteLength = byteLengthForBody(bytes);
@@ -1354,7 +1370,7 @@ var createTeakClient = (options) => {
         headers: idempotency(requestOptions),
         method: "POST"
       }, asCreate),
-      content: (id) => request(`${cardPath(id)}/content`, { method: "GET" }, asCardContent),
+      content: (id, contentOptions) => request(`${cardPath(id)}/content${contentOptions?.kind ? `?kind=${encodeURIComponent(contentOptions.kind)}` : ""}`, { method: "GET" }, asCardContent),
       delete: (id, deleteOptions) => request(`${cardPath(id)}${deleteOptions?.permanent ? "?permanent=true" : ""}`, { method: "DELETE" }, () => null),
       duplicate: (url) => request(`/v1/cards/duplicate?${new URLSearchParams({ url }).toString()}`, { method: "GET" }, (v) => isObject(v) && typeof v.cardId === "string" ? v.cardId : null),
       favorites: (input = {}) => request(`/v1/cards?${qs({ include: "content,metadata", ...input, favorited: true })}`, { method: "GET" }, asPage),
@@ -1407,6 +1423,12 @@ var createTeakClient = (options) => {
       removeCards: (id, cardIds) => request(`${folderPath(id)}/cards`, { body: JSON.stringify({ cardIds }), method: "DELETE" }, asFolderCards),
       update: (id, input) => request(folderPath(id), { body: JSON.stringify(input), method: "PATCH" }, asFolder)
     },
+    highlights: {
+      create: (cardId, input) => request(`${cardPath(cardId)}/highlights`, { body: JSON.stringify(input), method: "POST" }, asHighlight),
+      delete: (id) => request(highlightPath(id), { method: "DELETE" }, () => null),
+      list: (cardId) => request(`${cardPath(cardId)}/highlights`, { method: "GET" }, asHighlights),
+      update: (id, input) => request(highlightPath(id), { body: JSON.stringify(input), method: "PATCH" }, asHighlight)
+    },
     me: () => request("/v1/me", { method: "GET" }, asMe),
     tags: {
       delete: (tag) => request("/v1/tags/delete", { body: JSON.stringify({ tag }), method: "POST" }, asTagOperation),
@@ -1415,6 +1437,9 @@ var createTeakClient = (options) => {
       operation: (id) => request(`/v1/tags/operations/${encodeURIComponent(id)}`, { method: "GET" }, asTagOperation),
       rename: (from, to) => request("/v1/tags/rename", { body: JSON.stringify({ from, to }), method: "POST" }, asTagOperation)
     },
+    pageSnapshots: {
+      createUpload: (input) => request("/v1/page-snapshots/upload", { body: JSON.stringify(input), method: "POST" }, asUpload)
+    },
     uploads: {
       create: (input) => request("/v1/uploads", { body: JSON.stringify(input), method: "POST" }, asUpload),
       putFile

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "teak-sdk",
-  "version": "1.0.89",
+  "version": "1.0.91",
   "description": "Teak API client and OAuth discovery for browser and Node applications.",
   "repository": {
     "type": "git",

package/types/convex/shared/constants.d.ts

@@ -20,7 +20,18 @@ export declare const COLOR_HUE_ALIAS_MAP: Record<string, ColorHueBucket>;
 export declare function normalizeColorHueBucket(value: string): ColorHueBucket | null;
 export declare function normalizeHueFilters(values?: string[]): ColorHueBucket[];
 export declare const FREE_TIER_LIMIT = 200;
+/** The most links one paste into the web composer saves (card/pasteLinks.ts). */
+export declare const LINK_PASTE_LIMIT = 100;
+/** The most lines one paste may send; the composer sends no more. */
+export declare const LINK_PASTE_MAX_INPUT = 1000;
+/** Refused while the account's last pasted links are still being saved. */
+export declare const LINK_PASTE_ACTIVE_CODE = "PASTE_ACTIVE";
 export declare const TRASH_RETENTION_MS: number;
+/**
+ * The most cards Trash's count reads (card/emptyTrash.ts). A Trash this full
+ * or fuller shows the count with a plus; Empty Trash still deletes them all.
+ */
+export declare const TRASH_COUNT_LIMIT = 500;
 export { MAX_FILE_SIZE } from "./fileFormats.js";
 export declare const MAX_FILES_PER_UPLOAD = 20;
 export declare const MULTIPART_UPLOAD_THRESHOLD: number;

package/types/index.d.ts

@@ -8,7 +8,7 @@ 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 declare const ERROR_CODES: readonly ["AUTH_REQUIRED", "BAD_REQUEST", "CARD_LIMIT_REACHED", "CONFIG_ERROR", "CONFLICT", "CONTENT_TOO_LARGE", "FILE_TOO_LARGE", "FOLDER_LIMIT", "FORBIDDEN", "HIGHLIGHT_LIMIT", "IN_PROGRESS", "INTERNAL_ERROR", "INVALID_API_KEY", "INVALID_INPUT", "INVALID_STORAGE_KEY", "INVALID_UTF8", "LIMIT_REACHED", "METHOD_NOT_ALLOWED", "NETWORK_ERROR", "NOT_FOUND", "NO_ARTICLE", "NO_CONTENT", "NOT_IN_TRASH", "PAGE_SNAPSHOT_TOO_LARGE", "PARSE_ERROR", "QUOTE_NOT_FOUND", "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
@@ -21,13 +21,32 @@ export interface TokenProvider {
     getAccessToken: () => Promise<string | null> | string | null;
     onUnauthorized?: (rejectedToken: string) => Promise<string | null> | string | null;
 }
+/** A link's saved copy of its page. The HTML itself stays in Teak. */
+export interface CardArchive {
+    bytes: number;
+    capturedAt: number;
+    kind: "full" | "text_only";
+}
+/** A link's article, from its saved copy; read it with `cards.content(id, { kind: "article" })`. */
+export interface CardArticle {
+    readingMinutes: number;
+    wordCount: number;
+}
 export interface Card {
     aiSummary: string | null;
     aiTags: string[];
     aiTranscript: string | null;
     appUrl: string;
+    /**
+     * A link's saved copy of its page: `full`, or `text_only` when the page
+     * was too large; null until it is saved and for other cards. Servers that
+     * predate saved copies leave it out.
+     */
+    archive?: CardArchive | null;
     /** When the card was archived, or null. */
     archivedAt: number | null;
+    /** A link's article; null when it has none or it isn't ready. */
+    article?: CardArticle | null;
     /** Bar heights 0-100: 45 for a grid card, 200 for a player. */
     audioWaveform: {
         detail: number[];
@@ -58,6 +77,11 @@ export interface Card {
     fileUrl: string | null;
     /** Ids of the folders the card is in. */
     folderIds: string[];
+    /**
+     * Passages highlighted in a link's article; 0 for other cards. Servers
+     * that predate highlights leave it out.
+     */
+    highlightCount?: number;
     id: string;
     /** Archived cards are hidden from the library but still count. */
     isArchived: boolean;
@@ -115,6 +139,11 @@ export interface Card {
     notes: string | null;
     placeholderUrl: string | null;
     processingStatus: Record<string, unknown> | null;
+    /**
+     * When the card was last saved: `createdAt`, or later when the same link
+     * was saved again. Lists order by it. Servers that predate it leave it out.
+     */
+    savedAt?: number;
     screenshotUrl: string | null;
     /**
      * The title of the page in `sourceUrl`. Servers that predate sources
@@ -220,6 +249,28 @@ export interface TagOperation {
     total: number;
     updatedAt: number;
 }
+/** A passage highlighted in a link's article, with an optional note. */
+export interface Highlight {
+    /** False until the quote is found in the card's saved article. */
+    anchored: boolean;
+    cardId: string;
+    createdAt: number;
+    id: string;
+    note: string | null;
+    quote: string;
+    /** `reader`, `api` or `import`; accept values this SDK doesn't know. */
+    source: string;
+    updatedAt: number;
+}
+export interface CreateHighlightInput {
+    note?: string;
+    /** Text just before the quote, to pick one of its repeats. */
+    prefix?: string;
+    /** Text from the article; whitespace, curly quotes and case needn't match. */
+    quote: string;
+    /** Text just after the quote, to pick one of its repeats. */
+    suffix?: string;
+}
 export interface FolderCardsResult {
     failedIds: string[];
     /** Failed cards that are already in the most folders a card can be in. */
@@ -251,6 +302,12 @@ export interface CreateCardInput {
     mimeType?: string;
     /** Free-form notes attached to the card. */
     notes?: string | null;
+    /**
+     * The `fileKey` from `pageSnapshots.createUpload`: the page as the browser
+     * showed it, which becomes a link's saved copy. Ignored when it isn't one
+     * of your snapshot uploads.
+     */
+    pageSnapshotKey?: string;
     /**
      * 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`.
@@ -331,6 +388,10 @@ export interface CreateUploadInput {
     mimeType: string;
 }
 /** A link image upload: JPEG, PNG, WebP, GIF or AVIF, under 20 MB. */
+export interface CreatePageSnapshotUploadInput {
+    /** The gzipped page's exact size; at most 20 MiB. */
+    bytes: number;
+}
 export interface CreateThumbnailUploadInput {
     fileSize: number;
     mimeType: string;
@@ -346,7 +407,16 @@ export interface CreateCardResponse {
     appUrl: string;
     card?: Card;
     cardId: string;
+    /**
+     * True when the link was already in Teak: no card was made, and that card
+     * (`cardId`) moved to the top. Tags and notes sent with the save were not
+     * applied; update the card to add them.
+     */
+    resaved?: true;
+    /** `status` stays `created` for a re-save too. */
     status: "created";
+    /** True when the re-saved card was archived; it is back in the library. */
+    wasArchived?: true;
 }
 export interface RefreshCardResponse {
     cardId: string;
@@ -360,6 +430,8 @@ export interface SavedPdf {
     /** False when an earlier save already made that card. */
     created: boolean;
 }
+/** The kinds of stored text a card can have. */
+export type CardContentKind = "article" | "document" | "transcript" | "content";
 /** A card's full stored text (GET /v1/cards/:id/content). */
 export interface CardContent {
     cardId: string;
@@ -367,9 +439,11 @@ export interface CardContent {
     charCount: number;
     /**
      * document: extracted from the card's file; transcript: its speech;
-     * content: a text or quote card's written text.
+     * content: a text or quote card's written text; article: a link's article
+     * as Markdown, with image links valid for 7 days. A kind this SDK doesn't
+     * know yet comes through as a string rather than an error.
      */
-    kind: "document" | "transcript" | "content";
+    kind: CardContentKind | (string & {});
     text: string;
     /** The document is longer than Teak keeps. */
     truncated: boolean;
@@ -452,9 +526,13 @@ export declare const createTeakClient: (options: {
         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.
+         * card's content. `{ kind: "article" }` reads a link's article as
+         * Markdown; `kind` picks one kind when a card has several. Throws
+         * NO_CONTENT when the card has none (of that kind).
          */
-        content: (id: string) => Promise<CardContent>;
+        content: (id: string, contentOptions?: {
+            kind?: CardContentKind;
+        }) => Promise<CardContent>;
         /** Moves the card to Trash, or deletes it for good with `permanent`. */
         delete: (id: string, deleteOptions?: {
             permanent?: boolean;
@@ -547,6 +625,25 @@ export declare const createTeakClient: (options: {
             query?: string;
         }) => Promise<Folder>;
     };
+    highlights: {
+        /**
+         * Highlights a passage of a link's saved article, found by its text:
+         * the first match unless `prefix` or `suffix` points at another. An
+         * overlapping highlight merges with it. 409 NO_ARTICLE without a saved
+         * article, 422 QUOTE_NOT_FOUND, 409 HIGHLIGHT_LIMIT past 200.
+         */
+        create: (cardId: string, input: CreateHighlightInput) => Promise<Highlight>;
+        /** Removes a highlight and its note. */
+        delete: (id: string) => Promise<null>;
+        /** A card's highlights, in the order they appear in its article. */
+        list: (cardId: string) => Promise<{
+            items: Highlight[];
+        }>;
+        /** Writes or changes a highlight's note; `note: null` clears it. */
+        update: (id: string, input: {
+            note: string | null;
+        }) => Promise<Highlight>;
+    };
     me: () => Promise<Me>;
     tags: {
         /**
@@ -564,6 +661,14 @@ export declare const createTeakClient: (options: {
         /** Renames a tag on every card; it finishes in the background. */
         rename: (from: string, to: string) => Promise<TagOperation>;
     };
+    pageSnapshots: {
+        /**
+         * A signed URL for the page a browser extension saw, gzipped: `PUT`
+         * it with `Content-Type: application/gzip`, then pass the `fileKey`
+         * to `cards.create` as `pageSnapshotKey`.
+         */
+        createUpload: (input: CreatePageSnapshotUploadInput) => Promise<CreateUploadResponse>;
+    };
     uploads: {
         create: (input: CreateUploadInput) => Promise<CreateUploadResponse>;
         putFile: (uploadUrl: string, bytes: BodyInit, mimeType: string) => Promise<{