@lanes-sh/link 0.3.2 → 0.4.1

package/src/providers/reddit/index.ts

@@ -0,0 +1,113 @@
+import { defineProvider } from '#connectivity';
+import {
+  REDDIT_APP,
+  REDDIT_REDIRECT_URI,
+  REDDIT_SCOPES,
+  REDDIT_USER_AGENT,
+  specPath,
+} from './oauth.ts';
+import { REDDIT_REDACT } from './redact.ts';
+
+/**
+ * Reddit, through its own REST API.
+ *
+ * No MCP server exists to proxy and no OpenAPI document is published, so the
+ * spec beside this file is hand-authored — fifteen operations chosen rather
+ * than a whole API filtered down. That is a real cost and it buys the thing
+ * ADR-008 is about: the operations still become capabilities mechanically, and
+ * there is no per-endpoint translation code anywhere in this folder.
+ *
+ * Reddit was the first provider to need three things the transports did not
+ * have — a form-encoded request body, a `User-Agent`, and an OAuth redirect on
+ * a port fixed in advance. All three are now general, because each was a gap
+ * rather than a Reddit quirk: the last one is the exact reason `../github`
+ * gives for using a pasted token instead of OAuth.
+ */
+export const reddit = defineProvider({
+  id: 'reddit',
+  name: 'Reddit',
+  description:
+    'Read subreddits, posts, comments, and search, and post, comment, vote, and edit as your account, via the Reddit API.',
+  connector: {
+    kind: 'http',
+    // Host only. Reddit puts no version in the path, and this must equal the
+    // spec's `servers[0].url` — `cli/tools.test.ts` checks that they agree.
+    base_url: 'https://oauth.reddit.com',
+    openapi: specPath('reddit.v1.json'),
+    headers: { 'User-Agent': REDDIT_USER_AGENT },
+  },
+  auth: {
+    kind: 'oauth',
+    registration: 'manual',
+    app: REDDIT_APP,
+    /**
+     * `www.reddit.com` for the grant, `oauth.reddit.com` for the API. Mixing
+     * the two 404s, and the 404 says nothing about which half was wrong.
+     */
+    authorize_url: 'https://www.reddit.com/api/v1/authorize',
+    token_url: 'https://www.reddit.com/api/v1/access_token',
+    redirect_uri: REDDIT_REDIRECT_URI,
+    scopes: [...REDDIT_SCOPES],
+    /**
+     * Without `duration=permanent` Reddit returns an access token and no
+     * refresh token. The connection then works for exactly one hour and stops,
+     * which is a miserable thing to debug an hour after a successful connect —
+     * the same failure `authorize_params` was added for, where Google needs
+     * `access_type=offline`.
+     */
+    authorize_params: { duration: 'permanent' },
+    revoke_url: 'https://www.reddit.com/api/v1/revoke_token',
+  },
+  identity: { kind: 'http', url: 'https://oauth.reddit.com/api/v1/me', field: 'name' },
+  redact: REDDIT_REDACT,
+  /**
+   * Said once here rather than left for the tool descriptions to imply.
+   *
+   * Both are things an agent gets wrong on the first attempt and cannot learn
+   * from the error: Reddit answers a bare id with a generic failure, and a
+   * subreddit that requires a flair rejects the submission without saying that
+   * a flair was what was missing.
+   */
+  hints: {
+    add_comment:
+      'thing_id must be a fullname — t3_<id> for a post, t1_<id> for a comment — not the bare id that appears in a URL.',
+    submit_post:
+      'Many subreddits reject a submission with no flair. Call list_flairs first and pass flair_id, and read get_rules when posting somewhere unfamiliar.',
+  },
+  setup: {
+    summary:
+      'Reddit needs an app of your own, which takes a couple of minutes in a browser. There is no shared ' +
+      'client for this one on purpose: Reddit rate-limits per client id, so a client everyone shared would ' +
+      'mean strangers using up your hundred requests a minute. Your own app gets its own budget.',
+    docs: 'docs/detailed/setup/reddit.md',
+    docs_url: 'https://www.reddit.com/prefs/apps',
+    steps: [
+      'Open https://www.reddit.com/prefs/apps and choose "create another app...".',
+      'Name it something you will recognise later — the name is how you revoke this one without touching your others.',
+      'Choose "web app". "script" only ever reaches your own account, and "installed app" has no secret for this to hold.',
+      `Set the redirect uri to exactly ${REDDIT_REDIRECT_URI} — Reddit matches it character for character, and this is the address this command listens on.`,
+      'Create the app. The client id is the string under the app name; the secret is the field labelled "secret".',
+      'Reddit also asks you to register for API access separately, from the link on that page. Creating the app is not the same as being allowed to call the API.',
+      'If you regenerate the secret later, run: lanes link connect reddit --replace.',
+    ],
+    troubleshooting:
+      'Reddit refused the connection. If the browser said "invalid redirect_uri", the value registered on the app ' +
+      `is not exactly ${REDDIT_REDIRECT_URI}. If the call failed after connecting, the app exists but API access ` +
+      'has not been granted — that is a separate registration, linked from https://www.reddit.com/prefs/apps. ' +
+      'A 429 means the hundred-per-minute limit for this client id was reached.',
+    prompts: [
+      {
+        key: 'client_id',
+        label: 'Reddit client ID',
+        secret: false,
+        credential_ref: `${REDDIT_APP}/client_id`,
+      },
+      {
+        key: 'client_secret',
+        label: 'Reddit client secret',
+        secret: true,
+        credential_ref: `${REDDIT_APP}/client_secret`,
+      },
+    ],
+  },
+});

package/src/providers/reddit/oauth.ts

@@ -0,0 +1,77 @@
+/**
+ * The Reddit client, and why it is the operator's rather than ours.
+ *
+ * Every other pre-registered provider here reaches for the broker ADR-028
+ * built: one client Lanes operates, so nobody visits a console. That is the
+ * right default and it is the wrong answer for Reddit, for a reason particular
+ * to how Reddit meters access.
+ *
+ * Reddit's rate limit is a hundred queries a minute *per OAuth client id* —
+ * not per user, not per token. A shared client would pool every install of this
+ * program into one bucket, so the limit would be reached by strangers and the
+ * failure would arrive as somebody else's traffic. An operator registering
+ * their own gets their own hundred, which is the whole budget for one person
+ * and nowhere near it for the next.
+ *
+ * The cost is a console visit, which is what the broker exists to avoid. It is
+ * worth paying once here because the alternative degrades with every new user,
+ * and a shared limit is not a thing a later change could unpick.
+ */
+export const REDDIT_APP = 'reddit';
+
+/**
+ * How this program names itself to Reddit.
+ *
+ * Reddit asks callers to identify themselves and throttles the default agent
+ * hardest — a client that does not set one is treated as a scraper, which
+ * surfaces as sporadic 429s rather than as a refusal anybody can read. Nothing
+ * else in this repository sets a `User-Agent`, so `connector.headers` is what
+ * carries it.
+ *
+ * Reddit's documented format ends with the author's handle. That is omitted
+ * deliberately: this file is public, a handle is a real identifier, and
+ * `architecture.test.ts` refuses one anywhere a reader can see. A descriptive
+ * name and a URL satisfy what the throttle actually looks for.
+ */
+export const REDDIT_USER_AGENT = 'lanes-link/0.3 (+https://lanes.sh/link)';
+
+/**
+ * Where the browser comes back to, named to Reddit exactly as written.
+ *
+ * Reddit matches `redirect_uri` byte for byte, and `connect` normally listens
+ * on whatever port the kernel hands out — so a URL registered in the console
+ * months earlier could never match. Declaring it pins the listener to this
+ * port instead. See `cli/oauth.ts` and ADR-045.
+ *
+ * The port is high and otherwise unused, which is the only property it needs:
+ * nothing else in this program listens here, and the operator types the same
+ * string into Reddit's form.
+ */
+export const REDDIT_REDIRECT_URI = 'http://127.0.0.1:8765/callback';
+
+/**
+ * What the browser grant asks for.
+ *
+ * `identity` and `read` carry the reads; `submit` posts and comments; `edit`,
+ * `vote`, `save`, and `flair` cover what an author does to their own content
+ * afterwards. `mysubreddits` is what lists the subreddits this account follows.
+ *
+ * Absent on purpose: `privatemessages`, `history`, and every `mod*` scope.
+ * Nothing vendored needs them, and a scope on the consent screen that no tool
+ * can use is a grant asked for and never spent.
+ */
+export const REDDIT_SCOPES = [
+  'identity',
+  'read',
+  'submit',
+  'edit',
+  'vote',
+  'save',
+  'flair',
+  'mysubreddits',
+] as const;
+
+/** Resolve a vendored spec beside this folder. */
+export function specPath(name: string): string {
+  return new URL(`./specs/${name}`, import.meta.url).pathname;
+}

package/src/providers/reddit/redact.ts

@@ -0,0 +1,33 @@
+/**
+ * What survives into the audit log when Reddit is written to.
+ *
+ * The line is Gmail's and Slack's, because it is the same object: something a
+ * person wrote for other people to read. Where it went is recorded, what it
+ * said is not. A log that quoted the body would be a second copy of everything
+ * this account has ever posted, held somewhere nobody expects one.
+ *
+ * `title` is withheld along with the body, which is worth saying because it
+ * looks like metadata and is not — a Reddit title is usually the whole of the
+ * post, and the body is often empty. Keeping it would defeat the rest.
+ *
+ * Keys are the *shortened* names. `shortenName` strips a redundant provider
+ * prefix, so these must match what the capability is finally called — keying
+ * this block on anything else matches nothing and withholds everything,
+ * silently and with the log still looking correct.
+ */
+export const REDDIT_REDACT: Record<string, string[]> = {
+  // Everything that says where the post went and how it was marked, and nothing
+  // that says what it said. `url` is withheld with the body: for kind="link"
+  // the URL *is* the submission.
+  submit_post: ['sr', 'kind', 'flair_id', 'nsfw', 'spoiler', 'sendreplies', 'api_type'],
+  add_comment: ['thing_id', 'api_type'],
+  edit_text: ['thing_id', 'api_type'],
+  // Kept whole. Every argument is an identifier or a value from a fixed
+  // vocabulary, and an entry recording that something was voted on without
+  // recording which way records nothing anyone would look for — the reading
+  // that lets Slack keep an emoji name.
+  vote: ['id', 'dir'],
+  delete_thing: ['id'],
+  save_thing: ['id', 'category'],
+  set_flair: ['sr', 'link', 'flair_template_id', 'api_type'],
+};

package/src/providers/reddit/scopes.ts

@@ -0,0 +1,27 @@
+import type { ScopeMeaning } from '../scopes.ts';
+
+/**
+ * Reddit's scopes, in Reddit's own words.
+ *
+ * Taken verbatim from `https://www.reddit.com/api/v1/scopes`, which publishes a
+ * description per scope, rather than paraphrased. A paraphrase is where a
+ * consent screen quietly starts understating what it asks for, and the vendor's
+ * own sentence is the one that can be checked against the vendor.
+ *
+ * Three are marked broad, and all three for the same reason: they act publicly
+ * as the person. A post, a comment, a vote, and an edit are visible under their
+ * username to everyone who reads the subreddit, and unlike a private write they
+ * cannot be quietly undone — `delete` leaves the fact of the deletion behind,
+ * and anything cached or quoted stays. `read` is not marked: it reaches only
+ * what the account can already see, and Reddit's readable surface is public.
+ */
+export const REDDIT_SCOPE_MEANINGS: Record<string, ScopeMeaning> = {
+  identity: { meaning: 'read your username and signup date' },
+  read: { meaning: 'read posts and comments' },
+  submit: { meaning: 'post and comment publicly as you', broad: true },
+  edit: { meaning: 'edit and delete your posts and comments', broad: true },
+  vote: { meaning: 'vote on posts and comments as you', broad: true },
+  save: { meaning: 'save and unsave posts and comments' },
+  flair: { meaning: 'set the flair on your posts' },
+  mysubreddits: { meaning: 'list the subreddits you belong to' },
+};