@vibes.diy/prompts 14.1.28 → 14.1.30

package/llms/connections.md

@@ -2,7 +2,7 @@
 
 A **connection** lets a visitor link their own third-party account (GitHub,
 Threads, Instagram) to your app in one click, and lets your `backend.js` read
-from that account as them. The platform shows the consent screen, runs the
+from that account — and, when they approve it, post to it — as them. The platform shows the consent screen, runs the
 sign-in, holds the credential, refreshes it, and warns the person before it
 expires. Your app contains **no** client id, secret, redirect route, token
 field, or refresh code.
@@ -48,16 +48,25 @@ refuses the push. `why` is **required** and is shown to the visitor verbatim on
 the consent card, quoted as the app's own words — write it for them ("Show your
 GitHub profile next to your entries."), never as a note to yourself.
 
-| provider    | scope                      | what it buys (read-only)                                    |
-| ----------- | -------------------------- | ----------------------------------------------------------- |
-| `github`    | `read:user`                | the account's profile (`github(ctx).me()`)                  |
-| `threads`   | `threads_basic`            | the account's profile and its own posts                     |
-| `instagram` | `instagram_business_basic` | the account's profile and its own media with like/comment counts |
-
-Every connection is **read-only today**: nothing posts, replies, or writes on
-the person's behalf, and there is no scope for that. Instagram views and plays
-(the `insights` edge) are not available yet either. Build the app around what
-the table gives you; do not add a token field for the rest.
+| provider    | scope                                 | what it buys                                                     |
+| ----------- | ------------------------------------- | ---------------------------------------------------------------- |
+| `github`    | `read:user`                           | read the account's profile (`github(ctx).me()`)                  |
+| `threads`   | `threads_basic`                       | read the account's profile and its own posts                     |
+| `threads`   | `threads_content_publish`             | **post to their Threads feed** (`threads(ctx).publish()`)        |
+| `instagram` | `instagram_business_basic`            | read the account's profile and its own media with like/comment counts |
+| `instagram` | `instagram_business_content_publish`  | **post a photo or video to their Instagram** (`instagram(ctx).publish()`) |
+
+**A scope that posts is a separate scope, and asking for it is the whole
+authorization.** Declare it only when the app really posts, and say so in `why`
+— the visitor sees "Post to your Threads feed as you" beside your sentence and
+decides. An app that declared only the read scopes cannot post: the platform
+refuses the call, not because posting is forbidden but because nobody agreed to
+it.
+
+**GitHub is read-only on this lane** — there is no GitHub write scope to
+declare. Instagram views and plays (the `insights` edge) are not available
+either. Build the app around what the table gives you; do not add a token field
+for the rest.
 
 ### 2. Ask for it — `App.jsx`
 
@@ -115,6 +124,24 @@ provider call as a typed request with a typed response, so there is no
 - `instagram(ctx).me()` → `{ id, username }`; `instagram(ctx).media({ limit, cursor })` →
   `{ items: [{ id, caption, mediaType, permalink, timestamp, likeCount, commentsCount }], cursor? }`
   (`likeCount` is `null` when the person hides likes, never `0`).
+- `threads(ctx).publish({ text, imageUrl?, replyToId? })` → `{ id }`. Needs
+  `threads_content_publish`. A text post needs `text`; an image post needs a
+  publicly reachable `imageUrl` the provider fetches itself.
+- `instagram(ctx).publish({ imageUrl, caption? })` → `{ id }`. Needs
+  `instagram_business_content_publish`. Instagram has no text-only post, so
+  `imageUrl` is required.
+
+**Video posting is not available on either provider yet** — the provider hands
+back a container while the video is still processing, and the platform cannot
+yet read that container's status, so a video post would intermittently fail
+rather than land. Build on text and images; do not work around it with a raw
+`ctx.connections` call, which hits the same race.
+
+Posting on someone's behalf is a real act, so **let the person press the
+button** — post from a `fetch` route the app calls on an explicit action, and
+never from a `scheduled` tick that posts for a visitor who is not there. A post
+that fails is worth telling them about, so surface the thrown error rather than
+swallowing it.
 
 Page with `cursor` until it is absent. A provider error surfaces as a thrown
 `ProviderResponseError` with `status`; a connection problem surfaces as a
@@ -148,4 +175,9 @@ tell the app is waiting.
   the platform owns all of it.
 - No `Authorization: Bearer …` header built in app code; `ctx.connections`
   attaches the credential.
-- No posting: `POST`/`PUT`/`DELETE` through `ctx.connections` is refused.
+- No posting a person did not ask for: declare a publish scope only when the
+  app posts, and post on an action they took, never on a timer behind their
+  back.
+- No pretending an app can post without declaring it — a `POST` under a
+  read-only declaration is refused, and the fix is the declaration plus a
+  re-approval, not a retry.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibes.diy/prompts",
-  "version": "14.1.28",
+  "version": "14.1.30",
   "type": "module",
   "main": "./index.js",
   "exports": {
@@ -34,9 +34,9 @@
   "license": "Apache-2.0",
   "dependencies": {
     "@adviser/cement": "~0.5.34",
-    "@vibes.diy/call-ai-v2": "14.1.28",
-    "@vibes.diy/identity": "14.1.28",
-    "@vibes.diy/use-vibes-types": "14.1.28",
+    "@vibes.diy/call-ai-v2": "14.1.30",
+    "@vibes.diy/identity": "14.1.30",
+    "@vibes.diy/use-vibes-types": "14.1.30",
     "arktype": "~2.2.3",
     "json-schema-faker": "~0.6.3"
   },