papiers 0.1.7 → 0.1.8

package/README.md

@@ -5,7 +5,9 @@ Search and read your Papiers library from the terminal.
 The CLI can inspect your saved documents, highlights, notes, and
 conversations. It changes your library only to import a public PDF or webpage
 (`papiers import --help`) or highlight a passage in a saved PDF or webpage
-(`papiers highlight --help`), and only with a token that allows it.
+(`papiers highlight --help`), and only with a token that allows it. With a
+token that allows it, an agent can also add links to your own Discover feed
+(`papiers feed --help`).
 
 ## Install
 

package/dist/index.js

@@ -413,6 +413,120 @@ function isNodeError(error) {
   return Boolean(error && typeof error === "object" && "code" in error);
 }
 
+// src/contracts.ts
+var PAPIERS_SCHEMA_VERSIONS = {
+  searchRequest: "papiers.search.request.v1",
+  search: "papiers.search.v1",
+  searchResultsRequest: "papiers.search.results.request.v1",
+  listRequest: "papiers.list.request.v1",
+  list: "papiers.list.v1",
+  readRequest: "papiers.read.request.v1",
+  read: "papiers.read.v1",
+  capabilities: "papiers.capabilities.v1",
+  importRequest: "papiers.import.request.v1",
+  import: "papiers.import.v1",
+  highlightRequest: "papiers.highlight.request.v1",
+  highlight: "papiers.highlight.v1",
+  feedLinkRequest: "papiers.discover.feed.link.request.v1",
+  feedLink: "papiers.discover.feed.link.v1",
+  error: "papiers.error.v1"
+};
+var PAPIERS_PUBLIC_DATA_PLANE_SCOPES = [
+  "library:metadata:read",
+  "library:search",
+  "content:search",
+  "content:snippet:read",
+  "content:read",
+  "content:structure:read"
+];
+var PAPIERS_PUBLIC_FEATURE_IDS = [
+  "document_content_read",
+  "non_document_kinds",
+  "content_search",
+  "list_cursors",
+  "read_cursors",
+  "read_section_scopes",
+  "read_context",
+  "read_locations",
+  "ranked_search_cursors",
+  "search_results_browse",
+  "public_id_projection_not_ready",
+  "queryIn:content",
+  "queryIn:all",
+  "queryIn:latex"
+];
+var PAPIERS_SEARCH_QUALITY_SIGNALS = [
+  "high",
+  "medium",
+  "low",
+  "empty"
+];
+var PAPIERS_SEARCH_RESULT_KINDS = [
+  "document",
+  "conversation",
+  "note"
+];
+var PAPIERS_SEARCH_EVIDENCE_KINDS = [
+  "passage",
+  "highlight",
+  "equation"
+];
+var PAPIERS_SEARCH_MATCH_REASONS = [
+  "title",
+  "doi",
+  "arxivId",
+  "pmid",
+  "passage",
+  "highlight",
+  "equation",
+  "conversation",
+  "note"
+];
+var PAPIERS_PUBLIC_NOT_READY_REASONS_BY_FEATURE = {
+  document_content_read: ["explicit_enablement_required"],
+  non_document_kinds: ["public_id_projection_not_ready"],
+  content_search: ["content_search_not_ready"],
+  list_cursors: ["cursor_signing_not_configured"],
+  read_cursors: [
+    "cursor_signing_not_configured",
+    "document_content_read_required"
+  ],
+  read_section_scopes: ["section_scoped_read_not_ready"],
+  read_context: ["read_context_not_ready"],
+  ranked_search_cursors: ["search_sessions_not_ready"],
+  search_results_browse: [
+    "content_search_not_ready",
+    "search_sessions_not_ready"
+  ]
+};
+var PAPIERS_PUBLIC_ERROR_CODES = [
+  "api_disabled",
+  "auth_missing",
+  "auth_invalid_format",
+  "auth_invalid",
+  "auth_wrong_surface",
+  "auth_scope_missing",
+  "feature_not_available",
+  "filter_not_supported",
+  "invalid_filter_field",
+  "invalid_filter_operator",
+  "invalid_filter_value",
+  "invalid_filter_combination",
+  "order_not_supported",
+  "unsupported_format",
+  "invalid_cursor",
+  "invalid_cursor_context",
+  "forbidden",
+  "invalid_request",
+  "not_found",
+  "source_superseded",
+  "stale_reference",
+  "content_limit_exceeded",
+  "request_limit_exceeded",
+  "rate_limited",
+  "internal_error"
+];
+
 // ../../src/shared/papiers-public-ids.ts
 var PAPIERS_PUBLIC_ID_PREFIX_BY_KIND = {
   document: "doc",
@@ -621,118 +735,6 @@ function isPublicIdForKind(value, kind) {
   return publicReadKindForId(value) === kind;
 }
 
-// src/contracts.ts
-var PAPIERS_SCHEMA_VERSIONS = {
-  searchRequest: "papiers.search.request.v1",
-  search: "papiers.search.v1",
-  searchResultsRequest: "papiers.search.results.request.v1",
-  listRequest: "papiers.list.request.v1",
-  list: "papiers.list.v1",
-  readRequest: "papiers.read.request.v1",
-  read: "papiers.read.v1",
-  capabilities: "papiers.capabilities.v1",
-  importRequest: "papiers.import.request.v1",
-  import: "papiers.import.v1",
-  highlightRequest: "papiers.highlight.request.v1",
-  highlight: "papiers.highlight.v1",
-  error: "papiers.error.v1"
-};
-var PAPIERS_PUBLIC_DATA_PLANE_SCOPES = [
-  "library:metadata:read",
-  "library:search",
-  "content:search",
-  "content:snippet:read",
-  "content:read",
-  "content:structure:read"
-];
-var PAPIERS_PUBLIC_FEATURE_IDS = [
-  "document_content_read",
-  "non_document_kinds",
-  "content_search",
-  "list_cursors",
-  "read_cursors",
-  "read_section_scopes",
-  "read_context",
-  "read_locations",
-  "ranked_search_cursors",
-  "search_results_browse",
-  "public_id_projection_not_ready",
-  "queryIn:content",
-  "queryIn:all",
-  "queryIn:latex"
-];
-var PAPIERS_SEARCH_QUALITY_SIGNALS = [
-  "high",
-  "medium",
-  "low",
-  "empty"
-];
-var PAPIERS_SEARCH_RESULT_KINDS = [
-  "document",
-  "conversation",
-  "note"
-];
-var PAPIERS_SEARCH_EVIDENCE_KINDS = [
-  "passage",
-  "highlight",
-  "equation"
-];
-var PAPIERS_SEARCH_MATCH_REASONS = [
-  "title",
-  "doi",
-  "arxivId",
-  "pmid",
-  "passage",
-  "highlight",
-  "equation",
-  "conversation",
-  "note"
-];
-var PAPIERS_PUBLIC_NOT_READY_REASONS_BY_FEATURE = {
-  document_content_read: ["explicit_enablement_required"],
-  non_document_kinds: ["public_id_projection_not_ready"],
-  content_search: ["content_search_not_ready"],
-  list_cursors: ["cursor_signing_not_configured"],
-  read_cursors: [
-    "cursor_signing_not_configured",
-    "document_content_read_required"
-  ],
-  read_section_scopes: ["section_scoped_read_not_ready"],
-  read_context: ["read_context_not_ready"],
-  ranked_search_cursors: ["search_sessions_not_ready"],
-  search_results_browse: [
-    "content_search_not_ready",
-    "search_sessions_not_ready"
-  ]
-};
-var PAPIERS_PUBLIC_ERROR_CODES = [
-  "api_disabled",
-  "auth_missing",
-  "auth_invalid_format",
-  "auth_invalid",
-  "auth_wrong_surface",
-  "auth_scope_missing",
-  "feature_not_available",
-  "filter_not_supported",
-  "invalid_filter_field",
-  "invalid_filter_operator",
-  "invalid_filter_value",
-  "invalid_filter_combination",
-  "order_not_supported",
-  "unsupported_format",
-  "invalid_cursor",
-  "invalid_cursor_context",
-  "forbidden",
-  "invalid_request",
-  "not_found",
-  "source_superseded",
-  "stale_reference",
-  "content_limit_exceeded",
-  "request_limit_exceeded",
-  "rate_limited",
-  "internal_error"
-];
-
 // ../../src/shared/papiers-public-source-domain.ts
 var papiers_public_source_domain_exports = {};
 __export(papiers_public_source_domain_exports, {
@@ -3170,6 +3172,16 @@ async function highlightDocument(config, fetchImpl, request) {
   assertPapiersHighlightResponse("highlight", body);
   return body;
 }
+var FEED_PATH = "/api/v1/papiers/discover/feed";
+function addFeedLink(config, fetchImpl, link) {
+  return requestPapiersApi(config, fetchImpl, FEED_PATH, {
+    method: "POST",
+    body: {
+      schemaVersion: PAPIERS_SCHEMA_VERSIONS.feedLinkRequest,
+      ...link
+    }
+  });
+}
 async function requestPapiersApi(config, fetchImpl, path, init) {
   if (!config.token) {
     throw new CliUsageError(
@@ -3292,10 +3304,14 @@ var PAPIERS_PUBLIC_DATA_PLANE_SCOPES2 = [
   "content:read",
   "content:structure:read"
 ];
+var PAPIERS_WRITE_SCOPES = [
+  "library:import",
+  "library:highlight",
+  "discover:feed"
+];
 var PAPIERS_PUBLIC_SCOPES = [
   ...PAPIERS_PUBLIC_DATA_PLANE_SCOPES2,
-  "library:import",
-  "library:highlight"
+  ...PAPIERS_WRITE_SCOPES
 ];
 var PAPIERS_HIGHLIGHT_MAX_SCOPE_PAGES = 20;
 var PAPIERS_HIGHLIGHT_MAX_PAGE = 1e4;
@@ -3778,6 +3794,7 @@ var HIGHLIGHT_VALUE_FLAGS = [
 ];
 var VALUE_FLAGS = /* @__PURE__ */ new Set([
   ...HIGHLIGHT_VALUE_FLAGS,
+  "reason",
   "api-url",
   "cursor",
   "document-id",
@@ -3897,6 +3914,7 @@ COMMANDS
   browse        Page through an earlier search's results
   import        Add a public PDF or webpage to your library
   highlight     Highlight a passage in a saved document
+  feed          Add links to your Discover feed
   auth          Sign in, check status, or sign out
   doctor        Check your setup, connection, and what's available
   version       Print the CLI version
@@ -3960,7 +3978,7 @@ OPTIONS
                        e.g. --filter lastEngagedAt.gte=30d --filter annotated=true. Fields/ops: help --all.
   --order-by KEY       addedAt:desc (default) or lastEngagedAt:desc. document kind only.
   --document-id ID     scope to documents: doc_\u2026 (comma-separated or repeated), or @-/@file.
-                       document and highlight only.
+                       document and highlight only; highlight also takes papiers://item/\u2026 locators.
   --since WHEN         only items at or after an ISO 8601 time, or an Nd shorthand (e.g. 30d).
                        highlight and conversation only.
   --limit N            max results, 1\u201350.
@@ -4040,6 +4058,20 @@ check import-status until it is ready or failed; any other status means it
 is still in progress. Ready means papiers read works on its documentId now.
 A status is as of that check: reprocessing or trashing the document can
 change it later.`,
+  feed: `papiers feed \u2014 add links to your own Discover feed.
+
+USAGE
+  papiers feed add URL [--reason TEXT] [--json]
+
+Needs a token created with "Allow adding to your Discover feed" (Settings ->
+API tokens). A link shows in the user's Discover feed, labeled with the
+token's name and your reason, once Papiers has prepared it (usually within
+minutes); it never adds to their library. Give a short reason in your own
+words: why this user would want it. Sending a link again updates its reason.
+Links must be public pages: not paywalled, with no sign-in or private token.
+The user's plan sets how many new links it takes; past that, the answer says
+when to try again. The answer says whether the link is preparing, ready or
+failed; send it again to see how it is now.`,
   highlight: `papiers highlight \u2014 highlight a passage in a saved PDF or webpage.
 
 USAGE
@@ -4244,6 +4276,8 @@ function parseCliArgs(argv) {
       }
       return command === "import" ? { type: "import", ...global, url: target } : { type: "import-status", ...global, operationId: target };
     }
+    case "feed":
+      return parseFeedCommand(rest, parsed, global);
     case "highlight": {
       assertAllowedFlags(
         parsed,
@@ -4290,7 +4324,11 @@ function parseCliArgs(argv) {
       assertAllowedFlags(parsed, LIST_VALUE_FLAGS, "list");
       assertAllowedBooleanFlags(parsed, IDS_PIPELINE_BOOLEAN_FLAGS, "list");
       assertNoExtraPositionals(command, rest);
-      const listDocumentIds = parseDocumentIdFlagValues(parsed, "list");
+      const listDocumentIds = parseDocumentIdFlagValues(
+        parsed,
+        "list",
+        parseListKind(parsed) === "highlight"
+      );
       const listOutput = parseIdsOutput(parsed, "list");
       return {
         type: "list",
@@ -4384,6 +4422,33 @@ function parsePrettyOutput(parsed, idsOnly) {
   }
   return true;
 }
+function parseFeedCommand(rest, parsed, global) {
+  const [subcommand, target, ...extra] = rest;
+  const name = `feed ${subcommand ?? ""}`.trim();
+  assertAllowedBooleanFlags(parsed, NO_COMMAND_BOOLEAN_FLAGS, name);
+  switch (subcommand) {
+    case "add": {
+      assertAllowedFlags(
+        parsed,
+        /* @__PURE__ */ new Set([...GLOBAL_VALUE_FLAGS, "reason"]),
+        name
+      );
+      assertNoExtraPositionals(name, extra);
+      if (!target) throw new CliUsageError("papiers feed add requires a URL.");
+      const reason = singleFlagValue(parsed, "reason");
+      return {
+        type: "feed-add",
+        ...global,
+        url: target,
+        ...reason !== void 0 ? { reason } : {}
+      };
+    }
+    default:
+      throw new CliUsageError(
+        "papiers feed takes add. Run papiers feed --help."
+      );
+  }
+}
 function parseAuthCommand(rest, parsed, global) {
   const [subcommand, ...extra] = rest;
   switch (subcommand) {
@@ -4624,7 +4689,7 @@ function parseSinceFlag(parsed, kind, command) {
   }
   return new Date(parsedMs).toISOString();
 }
-function parseDocumentIdFlagValues(parsed, command) {
+function parseDocumentIdFlagValues(parsed, command, acceptsItemLocators = false) {
   const rawDocumentIds = parsed.flags.get("document-id");
   if (!rawDocumentIds?.length) {
     return void 0;
@@ -4642,9 +4707,10 @@ function parseDocumentIdFlagValues(parsed, command) {
       `papiers ${command} --document-id file references must include a file path after @.`
     );
   }
-  if (documentIds.some((id) => !isDocumentIdSource(id) && !isDocumentPublicId(id))) {
+  const isDocumentId = acceptsItemLocators ? isDocumentReadIdentifier : isDocumentPublicId;
+  if (documentIds.some((id) => !isDocumentIdSource(id) && !isDocumentId(id))) {
     throw new CliUsageError(
-      `papiers ${command} --document-id currently accepts only doc_* IDs.`
+      acceptsItemLocators ? `papiers ${command} --document-id accepts only doc_* IDs or papiers://item locators.` : `papiers ${command} --document-id currently accepts only doc_* IDs.`
     );
   }
   const explicitDocumentIdCount = documentIds.filter(
@@ -5895,6 +5961,15 @@ async function runCli(argv, dependencies = {}) {
         );
         return 0;
       }
+      case "feed-add":
+        writeJson(
+          stdout,
+          await addFeedLink(config, resolveFetch(dependencies.fetch), {
+            url: command.url,
+            ...command.reason !== void 0 ? { reason: command.reason } : {}
+          })
+        );
+        return 0;
       case "import":
         writeJson(
           stdout,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "papiers",
-  "version": "0.1.7",
+  "version": "0.1.8",
   "description": "Read-only CLI for your Papiers library.",
   "license": "UNLICENSED",
   "homepage": "https://papiers.ai",

package/skills/papiers-research/SKILL.md

@@ -132,6 +132,14 @@ once for the full contract. `PAPIERS_TOKEN` must be configured.
   a formula, its last words as `--end`; both as you read them, on plain words:
   keep math, even a single symbol like V, out of both (formatting doesn't
   matter). If it repeats, add words until unique.
+- **Add to the user's Discover feed what you think they'd want to read.**
+  `papiers feed add URL --reason "..."` needs a token with "Allow adding to
+  your Discover feed". It puts the link in their own Discover feed in Papiers,
+  labeled with your token's name and your reason; it never touches their
+  library. Give a reason in your own words: why this user, given what you
+  know of them. Public pages only (not paywalled, nothing private in the
+  link). It shows once Papiers has prepared it, usually within minutes;
+  sending it again answers how it is now.
 - **Budgets are policy, not protocol.** Default to ~10–20 queries and 3–8
   document reads per task. The user may override any policy in this skill
   (read more, weight recency differently, skip curation); the loop's shape