@civitai/blocks-react 0.48.0 → 0.50.0

package/README.md

@@ -570,6 +570,80 @@ async function toggle() {
 Most blocks want `<FollowButton>` from `@civitai/blocks-react/ui` instead, which
 wires all of the above.
 
+### `useCreatePostFromApp()`
+
+Publish a **real, published Post on the viewer's profile** from this app's own
+outputs, host-mediated over `CREATE_POST_FROM_APP`. Returns
+`{ createPost, pending, error }`.
+
+The strictly-more-consequential sibling of `usePublishGenerationOutputs()`: that
+one makes a bare `Image` row with no post, no feed presence, no reward and no
+notification; this one makes **public, feed-visible, reward-earning content under
+the viewer's byline**.
+
+🔴 **Requires the `posts:write:self` scope**, which is **sensitive** and
+**consent-gated**. Declare it in your manifest *with* a `scopeJustifications`
+entry — the server rejects the manifest at submit without one — and expect the
+viewer to be prompted to grant it before the first call succeeds.
+
+🔴 **The grant is not the consent.** Every call opens a host-chrome confirm, and
+what it shows is the **server's** resolution of your request, never your strings:
+the tag names that will *actually* be applied, host-fetched model and version
+names for a gallery attach, and real thumbnails. A block cannot show one post and
+publish another.
+
+🔴 **No arm of `sources` takes a URL.** Name a workflow from this app's own
+subqueue plus indexes into its outputs, or `Image` ids from a previous
+`usePublishGenerationOutputs()` publish. The server re-verifies both — ownership,
+this app's provenance marker, and that the image is not already in a post.
+
+⚠️ **Posting a published image removes it from this app's own grid.** The
+app-scoped read behind `useGatedImages()` is conjoined with `postId IS NULL`, so
+an image that joins a post stops resolving there. An app cannot both keep an
+image in its shared grid and let the viewer post it — design around it.
+
+Text is advisory: the server bounds `title`/`detail`, screens them, refuses a
+`detail` containing a link, and resolves `tags` against **existing** tags only (a
+name matching no tag is dropped, never minted, and is shown to the viewer on the
+confirm).
+
+`createPost` **rejects** with a `CreatePostError` on every non-success:
+
+| | meaning | what to do |
+|---|---|---|
+| `err.declined` | the viewer dismissed the confirm — **no post was created** | revert, say nothing |
+| `err.signInRequired` | no session | route into `useRequestSignIn()` |
+| `err.timedOut` | no reply arrived within the 10-min consent bound | 🔴 **check this BEFORE `.message`** — it also has no `.code`, and its message is an SDK-internal string. It does **not** mean nothing happened; tell the viewer to check their profile and never retry automatically |
+| `err.code` set otherwise | a host refusal (`review-mode` / `block is not ready` / `no images to post` / `no block token`) | show or ignore per case |
+| `err.code === undefined` **and** `!err.timedOut` | a **server** message the host forwarded verbatim (rate limit, blocked title, refused gallery attach) | show `err.message` |
+
+```tsx
+const { createPost, pending } = useCreatePostFromApp();
+const { requestSignIn } = useRequestSignIn();
+
+async function share() {
+  try {
+    const post = await createPost({
+      sources: [{ kind: 'workflow', workflowId: w.workflowId, imageIndexes: [0, 2] }],
+      title: 'Made with Sticker Studio',
+    });
+    showToast(`Posted! ${post.url}`);
+  } catch (err) {
+    if (err instanceof CreatePostError) {
+      if (err.signInRequired) return requestSignIn();
+      if (err.declined) return; // the viewer said no — say nothing
+      if (err.timedOut) return showToast('Still working — check your profile.');
+      showToast(err.message); // a real server message, safe to render
+    }
+  }
+}
+```
+
+In `dev:mock` the `createPostResult` / `createPostError` scenario knobs drive
+both arms (including `declined`). **`dev:live` refuses this bridge on purpose** —
+it has no civitai chrome to render the server-resolved confirm in, and driving
+the write without it would let dev prove out a flow production does not have.
+
 ### `useAppWorkflows(params?)`
 
 The calling app's **own** generator subqueue — the tag-scoped list of generations
@@ -830,20 +904,48 @@ any request for a scope your dev token lacks produces one.
 
 ### `useDomainMaturity()`
 
-Read the surrounding color-domain's maturity ceiling (civitai #2670) so a block
-can hide/blur mature affordances on a SFW domain. **Fail-closed SFW** until
-`BLOCK_INIT` lands or against a host that predates the field.
+Read the maturity ceiling in force for the current viewer, so a block can
+hide/blur mature affordances. **Fail-closed SFW** until `BLOCK_INIT` lands or
+against a host that projects no ceiling.
 
 ```tsx
 const { isSfw, isLevelAllowed } = useDomainMaturity();
 const showRSlider = isLevelAllowed(BrowsingLevel.R);   // false on a SFW domain
 ```
 
+The gates account for **two** things, and the distinction matters:
+
+| field | answers |
+| --- | --- |
+| `maxBrowsingLevel` | what this **domain** permits anybody (identical for every viewer on it) |
+| `effectiveBrowsingLevel` | what **this viewer** may be shown here — the domain ceiling narrowed by their own NSFW setting |
+
+`isSfw` / `isLevelAllowed` gate on the second, so a viewer who turned NSFW off
+sees SFW affordances even on a mature domain. `effectiveBrowsingLevel` is always
+a subset of `maxBrowsingLevel`, so reading these can only ever show the viewer
+**less** — never more. Compare the two when you want to explain *why* something
+is hidden:
+
+```tsx
+const { maxBrowsingLevel, effectiveBrowsingLevel } = useDomainMaturity();
+const hiddenByYourSettings = effectiveBrowsingLevel !== maxBrowsingLevel;
+```
+
+The hook's name is historic — it shipped when the domain ceiling was the only
+signal. There is deliberately no separate viewer-maturity hook: two hooks would
+mean two answers to "may I show this", and the one named for the domain would be
+the wider of the pair.
+
+Drive it locally with `createMockHost({ domain: 'red', viewerBrowsingLevel: BrowsingLevel.PG })`.
+The mock clamps that option to its own ceiling exactly as the real host does, so
+you cannot test against a viewer wider than the domain — production cannot
+produce one either.
+
 ### `SfwGate`
 
-Convenience component that renders `children` only when the domain permits the
-maturity — no `level` prop gates on the SFW ceiling, a `level` prop gates on that
-browsing-level bit. Fail-closed SFW.
+Convenience component that renders `children` only when the current viewer may be
+shown them — no `level` prop gates on `isSfw`, a `level` prop gates on that
+browsing-level bit. Both account for the domain **and** the viewer. Fail-closed SFW.
 
 ```tsx
 function MatureSection() {
@@ -1039,6 +1141,7 @@ Runnable, minimal blocks — one per feature, each with its own README:
 
 | `@civitai/blocks-react` | pairs with `@civitai/app-sdk` | adds |
 |---|---|---|
+| `0.50.x` | `^0.40.0` | `useCreatePostFromApp()` (`CREATE_POST_FROM_APP`) + the `posts:write:self` scope. 🔴 Same wide `peerDependencies` floor as the row below, so **npm will not warn you**: pairing this with an SDK below `0.40.0` fails at `tsc` with `Cannot find name 'BlockCreatePostHostError'`, not at install. |
 | `0.48.x` | `^0.38.0` | `useCollectionFollow()` + `<FollowButton>` / `<TipButton>` (`SET_COLLECTION_FOLLOW`). 🔴 The `peerDependencies` floor stays the deliberately-wide `>=0.29.0 <1.0.0` (#206 — a per-minor floor forced a major on consumers), so **npm will not warn you**: pairing this with an SDK below `0.38.0` fails at `tsc` with `Cannot find name 'BlockCollectionFollowErrorCode'`, not at install. |
 | `0.36.x` | `^0.27.0` | auto-installs the SDK's opaque-origin web-storage shim (`@civitai/app-sdk/safe-storage`) on import |
 | `0.29.x` | `^0.24.0` | `useAppWorkflows()` — app generator subqueue read + cancel (`QUERY_APP_WORKFLOWS` / `CANCEL_APP_WORKFLOW`) |

package/dist/hooks/SfwGate.d.ts

@@ -8,25 +8,32 @@ export interface SfwGateProps {
     /**
      * When set, gate on `isLevelAllowed(level)` (a single `BrowsingLevel` bit)
      * instead of the coarse `isSfw`. Lets a block reveal a level-specific
-     * affordance (e.g. an R-rated toggle) only when the domain permits that level.
+     * affordance (e.g. an R-rated toggle) only when that level is permitted —
+     * by the domain AND by the viewer's own browsing-level setting.
      */
     level?: number;
     /** Rendered when the gate is closed. Defaults to `null` (render nothing). */
     fallback?: ReactNode;
 }
 /**
- * Convenience wrapper that renders `children` only when the surrounding
- * color-domain permits it, else `fallback` — so a block can hide/blur mature
- * affordances on a SFW domain without wiring {@link useDomainMaturity} by hand.
+ * Convenience wrapper that renders `children` only when the current viewer may
+ * be shown them here, else `fallback` — so a block can hide/blur mature
+ * affordances without wiring {@link useDomainMaturity} by hand.
  *
- * Gating:
- *  - no `level` prop → renders `children` when the domain is SFW (`isSfw`).
+ * Gating (both delegate to the hook, so both account for the DOMAIN's ceiling
+ * AND the VIEWER's own browsing level — see `effectiveBrowsingLevel`):
+ *  - no `level` prop → renders `children` when nothing mature may be shown
+ *    (`isSfw`).
  *  - `level` prop set → renders `children` when that browsing-level bit is
- *    allowed by the domain ceiling (`isLevelAllowed(level)`).
+ *    permitted (`isLevelAllowed(level)`).
+ *
+ * 🔴 A red-domain viewer who turned NSFW off closes this gate. That is the
+ * point: before the per-viewer ceiling existed, the gate opened for everyone on
+ * a mature domain regardless of their own setting.
  *
  * **Fail-closed SFW**: before `BLOCK_INIT` lands, and against a host that
- * predates civitai #2670 (no ceiling field), the gate is treated as SFW —
- * `children` show only for SFW content, mature content shows `fallback`.
+ * projects no ceiling at all, the gate is treated as SFW — `children` show only
+ * for SFW content, mature content shows `fallback`.
  *
  * @example
  * // Hide a mature-only carousel on a SFW domain:

package/dist/hooks/SfwGate.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"SfwGate.d.ts","sourceRoot":"","sources":["../../src/hooks/SfwGate.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAe,EAAE,EAAE,YAAY,GAAG,SAAS,CAIrF"}
+{"version":3,"file":"SfwGate.d.ts","sourceRoot":"","sources":["../../src/hooks/SfwGate.tsx"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC;AAIvC;;GAEG;AACH,MAAM,WAAW,YAAY;IAC3B,+EAA+E;IAC/E,QAAQ,EAAE,SAAS,CAAC;IACpB;;;;;OAKG;IACH,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,6EAA6E;IAC7E,QAAQ,CAAC,EAAE,SAAS,CAAC;CACtB;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,wBAAgB,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAe,EAAE,EAAE,YAAY,GAAG,SAAS,CAIrF"}

package/dist/hooks/SfwGate.js

@@ -1,17 +1,23 @@
 import { useDomainMaturity } from './useDomainMaturity.js';
 /**
- * Convenience wrapper that renders `children` only when the surrounding
- * color-domain permits it, else `fallback` — so a block can hide/blur mature
- * affordances on a SFW domain without wiring {@link useDomainMaturity} by hand.
+ * Convenience wrapper that renders `children` only when the current viewer may
+ * be shown them here, else `fallback` — so a block can hide/blur mature
+ * affordances without wiring {@link useDomainMaturity} by hand.
  *
- * Gating:
- *  - no `level` prop → renders `children` when the domain is SFW (`isSfw`).
+ * Gating (both delegate to the hook, so both account for the DOMAIN's ceiling
+ * AND the VIEWER's own browsing level — see `effectiveBrowsingLevel`):
+ *  - no `level` prop → renders `children` when nothing mature may be shown
+ *    (`isSfw`).
  *  - `level` prop set → renders `children` when that browsing-level bit is
- *    allowed by the domain ceiling (`isLevelAllowed(level)`).
+ *    permitted (`isLevelAllowed(level)`).
+ *
+ * 🔴 A red-domain viewer who turned NSFW off closes this gate. That is the
+ * point: before the per-viewer ceiling existed, the gate opened for everyone on
+ * a mature domain regardless of their own setting.
  *
  * **Fail-closed SFW**: before `BLOCK_INIT` lands, and against a host that
- * predates civitai #2670 (no ceiling field), the gate is treated as SFW —
- * `children` show only for SFW content, mature content shows `fallback`.
+ * projects no ceiling at all, the gate is treated as SFW — `children` show only
+ * for SFW content, mature content shows `fallback`.
  *
  * @example
  * // Hide a mature-only carousel on a SFW domain:

package/dist/hooks/SfwGate.js.map

@@ -1 +1 @@
-{"version":3,"file":"SfwGate.js","sourceRoot":"","sources":["../../src/hooks/SfwGate.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAkB3D;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,MAAM,UAAU,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,EAAgB;IACxE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,iBAAiB,EAAE,CAAC;IACtD,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACpC,CAAC"}
+{"version":3,"file":"SfwGate.js","sourceRoot":"","sources":["../../src/hooks/SfwGate.tsx"],"names":[],"mappings":"AAEA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAmB3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+BG;AACH,MAAM,UAAU,OAAO,CAAC,EAAE,QAAQ,EAAE,KAAK,EAAE,QAAQ,GAAG,IAAI,EAAgB;IACxE,MAAM,EAAE,KAAK,EAAE,cAAc,EAAE,GAAG,iBAAiB,EAAE,CAAC;IACtD,MAAM,IAAI,GAAG,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,cAAc,CAAC,KAAK,CAAC,CAAC;IACjE,OAAO,IAAI,CAAC,CAAC,CAAC,QAAQ,CAAC,CAAC,CAAC,QAAQ,CAAC;AACpC,CAAC"}

package/dist/hooks/useCreatePostFromApp.d.ts

@@ -0,0 +1,144 @@
+import type { BlockCreatePostHostError, BlockCreatePostRequest, BlockCreatePostResult, BlockPostSource } from '@civitai/app-sdk/blocks';
+export type { BlockCreatePostHostError, BlockCreatePostRequest, BlockCreatePostResult, BlockPostSource, };
+/**
+ * The closed set of HOST refusal codes, as a runtime Set.
+ *
+ * 🔴 THIS EXISTS BECAUSE THE ERROR CHANNEL IS NOT AN ENUM. The host sends either
+ * one of these codes or a free-text server message (a rate limit, a blocked
+ * title, a refused gallery attach), so "is this a code?" is a MEMBERSHIP
+ * question at runtime, not a type-level one — a `switch` over the union type
+ * would silently treat `"You do not have permission…"` as unmatched prose while
+ * a typo'd literal compiled fine. Derived from the array below so the two cannot
+ * drift, and mirrored from civitai/civitai's `CREATE_POST_HOST_ERRORS`.
+ */
+export declare const CREATE_POST_ERROR_CODES: readonly ["review-mode", "block is not ready", "sign in to post", "no images to post", "no block token", "declined"];
+/**
+ * `true` when `error` is one of the host's CLOSED refusal codes rather than a
+ * free-text server message.
+ *
+ * Use it before comparing against a code — see {@link CREATE_POST_ERROR_CODES}
+ * for why equality alone is not enough.
+ */
+export declare function isCreatePostErrorCode(error: string): error is BlockCreatePostHostError;
+/**
+ * A post-creation failure.
+ *
+ * `.code` is the host's refusal code when the host refused, and `undefined`
+ * otherwise.
+ *
+ * 🔴 `.code === undefined` IS NOT BY ITSELF "A SERVER MESSAGE WORTH SHOWING".
+ * TWO different failures land there: a server message the host forwarded
+ * verbatim, and a TRANSPORT TIMEOUT whose `.message` is an SDK-internal string.
+ * **Check `.timedOut` first**; `.code === undefined && !timedOut` is the branch
+ * whose `.message` is meant to be rendered.
+ */
+export declare class CreatePostError extends Error {
+    /** The closed host refusal code, or `undefined` for a server/transport error. */
+    readonly code?: BlockCreatePostHostError;
+    /**
+     * The SDK transport gave up waiting — no reply ever arrived.
+     *
+     * 🔴 CHECK THIS BEFORE SHOWING `.message`, and 🔴 DO NOT PRESENT IT AS
+     * "NOTHING HAPPENED". A timeout also has `code === undefined`, so "no code ⇒ a
+     * server message worth rendering" is false and acting on it puts an
+     * SDK-internal string in front of a viewer. More importantly the write may
+     * have LANDED and only the reply failed to arrive — and here the write is a
+     * PUBLIC POST under the viewer's name. Tell the viewer to check their profile;
+     * never retry automatically, which is how a duplicate post happens.
+     */
+    readonly timedOut: boolean;
+    /**
+     * The viewer DISMISSED the host's consent confirm, so NO POST WAS CREATED.
+     *
+     * 🔴 Not an error condition to shout about, and it is trustworthy in the one
+     * direction that matters: the host takes its consent latch SYNCHRONOUSLY
+     * before the write, so `declined` can never be reported for a post that
+     * landed. Revert optimistic state and render nothing.
+     */
+    readonly declined: boolean;
+    /**
+     * There is no session. Route this into `useRequestSignIn()` rather than
+     * showing an error — the viewer's next step is signing in, not retrying.
+     */
+    readonly signInRequired: boolean;
+    constructor(error: string, opts?: {
+        timedOut?: boolean;
+    });
+}
+/** What {@link useCreatePostFromApp} returns. */
+export interface UseCreatePostFromApp {
+    /**
+     * Ask the host to publish a REAL Post on the viewer's profile from this app's
+     * OWN outputs, and resolve with the created post.
+     *
+     * REJECTS with a {@link CreatePostError} on every non-success — including
+     * `declined`, which means the viewer dismissed the confirm and NO POST EXISTS.
+     * Check `.declined` before rendering a failure.
+     */
+    createPost: (args: BlockCreatePostRequest) => Promise<BlockCreatePostResult>;
+    /** `true` while a request is in flight (including the viewer's confirm). */
+    pending: boolean;
+    /**
+     * The last request's failure, or `null`. Cleared at the start of the next
+     * `createPost`. A dismissal lands here too — read `.declined`.
+     */
+    error: CreatePostError | null;
+}
+/**
+ * Publish a REAL, PUBLISHED Post on the VIEWER'S profile from the calling app's
+ * OWN outputs, through the host-mediated `CREATE_POST_FROM_APP` →
+ * `CREATE_POST_RESULT` bridge.
+ *
+ * The strictly-more-consequential sibling of `usePublishGenerationOutputs()`:
+ * that one makes a bare `Image` row with no post, no feed presence, no reward
+ * and no notification; this one makes public, feed-visible, reward-earning
+ * content under the viewer's byline.
+ *
+ * 🔴 REQUIRES THE `posts:write:self` SCOPE, which is SENSITIVE and
+ * CONSENT-GATED. Declare it in your manifest WITH a `scopeJustifications` entry
+ * — the server rejects the manifest at submit without one — and expect the
+ * viewer to be prompted to grant it before the first call succeeds.
+ *
+ * 🔴 THE SCOPE GRANT IS NOT THE CONSENT. Every call additionally opens a
+ * host-chrome confirm, and what that confirm shows is the SERVER'S resolution of
+ * your request, never your strings: the tag names that will ACTUALLY be applied,
+ * host-fetched model and version names for a gallery attach, and real
+ * thumbnails. A block cannot show one post and publish another.
+ *
+ * 🔴 NO ARM OF `sources` TAKES A URL. Name a workflow from this app's own
+ * subqueue plus indexes into its outputs, or `Image` ids from a previous
+ * `usePublishGenerationOutputs()` publish. The server re-verifies both.
+ *
+ * ⚠️ POSTING A PUBLISHED IMAGE REMOVES IT FROM THIS APP'S OWN GRID. The
+ * app-scoped read behind `useGatedImages()` is conjoined with `postId IS NULL`,
+ * so an image that joins a post stops resolving there. An app cannot both keep
+ * an image in its shared grid and let the viewer post it.
+ *
+ * Because the reply waits on a person, the request carries
+ * {@link HUMAN_INTERACTION_TIMEOUT_MS} (10 min) rather than the ~30s protocol
+ * default — it resolves the instant the viewer acts, and the ceiling only bounds
+ * an abandoned dialog.
+ *
+ * @example
+ * const { createPost, pending } = useCreatePostFromApp();
+ * const { requestSignIn } = useRequestSignIn();
+ *
+ * const share = async () => {
+ *   try {
+ *     const post = await createPost({
+ *       sources: [{ kind: 'workflow', workflowId: w.workflowId, imageIndexes: [0, 2] }],
+ *       title: 'Made with Sticker Studio',
+ *     });
+ *     showToast(`Posted! ${post.url}`);
+ *   } catch (e) {
+ *     if (e instanceof CreatePostError) {
+ *       if (e.signInRequired) return requestSignIn();
+ *       if (e.declined) return;                    // the viewer said no — say nothing
+ *       if (e.timedOut) return showToast('Still working — check your profile.');
+ *       showToast(e.message);                      // a real server message, safe to render
+ *     }
+ *   }
+ * };
+ */
+export declare function useCreatePostFromApp(): UseCreatePostFromApp;
+//# sourceMappingURL=useCreatePostFromApp.d.ts.map

package/dist/hooks/useCreatePostFromApp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCreatePostFromApp.d.ts","sourceRoot":"","sources":["../../src/hooks/useCreatePostFromApp.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EACV,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,EAChB,MAAM,yBAAyB,CAAC;AAMjC,YAAY,EACV,wBAAwB,EACxB,sBAAsB,EACtB,qBAAqB,EACrB,eAAe,GAChB,CAAC;AAEF;;;;;;;;;;GAUG;AACH,eAAO,MAAM,uBAAuB,sHAOoB,CAAC;AAIzD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,wBAAwB,CAEtF;AAED;;;;;;;;;;;GAWG;AACH,qBAAa,eAAgB,SAAQ,KAAK;IACxC,iFAAiF;IACjF,QAAQ,CAAC,IAAI,CAAC,EAAE,wBAAwB,CAAC;IACzC;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;;;;;OAOG;IACH,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B;;;OAGG;IACH,QAAQ,CAAC,cAAc,EAAE,OAAO,CAAC;gBAErB,KAAK,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,EAAE,OAAO,CAAA;KAAE;CAQzD;AAED,iDAAiD;AACjD,MAAM,WAAW,oBAAoB;IACnC;;;;;;;OAOG;IACH,UAAU,EAAE,CAAC,IAAI,EAAE,sBAAsB,KAAK,OAAO,CAAC,qBAAqB,CAAC,CAAC;IAC7E,4EAA4E;IAC5E,OAAO,EAAE,OAAO,CAAC;IACjB;;;OAGG;IACH,KAAK,EAAE,eAAe,GAAG,IAAI,CAAC;CAC/B;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuDG;AACH,wBAAgB,oBAAoB,IAAI,oBAAoB,CA6E3D"}

package/dist/hooks/useCreatePostFromApp.js

@@ -0,0 +1,213 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { HUMAN_INTERACTION_TIMEOUT_MS } from '../internal/requestTimeouts.js';
+import { getTransport } from '../internal/singleton.js';
+import { RequestTimeoutError, sendTypedRequest } from '../internal/transport.js';
+/**
+ * The closed set of HOST refusal codes, as a runtime Set.
+ *
+ * 🔴 THIS EXISTS BECAUSE THE ERROR CHANNEL IS NOT AN ENUM. The host sends either
+ * one of these codes or a free-text server message (a rate limit, a blocked
+ * title, a refused gallery attach), so "is this a code?" is a MEMBERSHIP
+ * question at runtime, not a type-level one — a `switch` over the union type
+ * would silently treat `"You do not have permission…"` as unmatched prose while
+ * a typo'd literal compiled fine. Derived from the array below so the two cannot
+ * drift, and mirrored from civitai/civitai's `CREATE_POST_HOST_ERRORS`.
+ */
+export const CREATE_POST_ERROR_CODES = [
+    'review-mode',
+    'block is not ready',
+    'sign in to post',
+    'no images to post',
+    'no block token',
+    'declined',
+];
+const CODE_SET = new Set(CREATE_POST_ERROR_CODES);
+/**
+ * `true` when `error` is one of the host's CLOSED refusal codes rather than a
+ * free-text server message.
+ *
+ * Use it before comparing against a code — see {@link CREATE_POST_ERROR_CODES}
+ * for why equality alone is not enough.
+ */
+export function isCreatePostErrorCode(error) {
+    return CODE_SET.has(error);
+}
+/**
+ * A post-creation failure.
+ *
+ * `.code` is the host's refusal code when the host refused, and `undefined`
+ * otherwise.
+ *
+ * 🔴 `.code === undefined` IS NOT BY ITSELF "A SERVER MESSAGE WORTH SHOWING".
+ * TWO different failures land there: a server message the host forwarded
+ * verbatim, and a TRANSPORT TIMEOUT whose `.message` is an SDK-internal string.
+ * **Check `.timedOut` first**; `.code === undefined && !timedOut` is the branch
+ * whose `.message` is meant to be rendered.
+ */
+export class CreatePostError extends Error {
+    /** The closed host refusal code, or `undefined` for a server/transport error. */
+    code;
+    /**
+     * The SDK transport gave up waiting — no reply ever arrived.
+     *
+     * 🔴 CHECK THIS BEFORE SHOWING `.message`, and 🔴 DO NOT PRESENT IT AS
+     * "NOTHING HAPPENED". A timeout also has `code === undefined`, so "no code ⇒ a
+     * server message worth rendering" is false and acting on it puts an
+     * SDK-internal string in front of a viewer. More importantly the write may
+     * have LANDED and only the reply failed to arrive — and here the write is a
+     * PUBLIC POST under the viewer's name. Tell the viewer to check their profile;
+     * never retry automatically, which is how a duplicate post happens.
+     */
+    timedOut;
+    /**
+     * The viewer DISMISSED the host's consent confirm, so NO POST WAS CREATED.
+     *
+     * 🔴 Not an error condition to shout about, and it is trustworthy in the one
+     * direction that matters: the host takes its consent latch SYNCHRONOUSLY
+     * before the write, so `declined` can never be reported for a post that
+     * landed. Revert optimistic state and render nothing.
+     */
+    declined;
+    /**
+     * There is no session. Route this into `useRequestSignIn()` rather than
+     * showing an error — the viewer's next step is signing in, not retrying.
+     */
+    signInRequired;
+    constructor(error, opts) {
+        super(error);
+        this.name = 'CreatePostError';
+        this.timedOut = opts?.timedOut === true;
+        if (isCreatePostErrorCode(error))
+            this.code = error;
+        this.declined = error === 'declined';
+        this.signInRequired = error === 'sign in to post';
+    }
+}
+/**
+ * Publish a REAL, PUBLISHED Post on the VIEWER'S profile from the calling app's
+ * OWN outputs, through the host-mediated `CREATE_POST_FROM_APP` →
+ * `CREATE_POST_RESULT` bridge.
+ *
+ * The strictly-more-consequential sibling of `usePublishGenerationOutputs()`:
+ * that one makes a bare `Image` row with no post, no feed presence, no reward
+ * and no notification; this one makes public, feed-visible, reward-earning
+ * content under the viewer's byline.
+ *
+ * 🔴 REQUIRES THE `posts:write:self` SCOPE, which is SENSITIVE and
+ * CONSENT-GATED. Declare it in your manifest WITH a `scopeJustifications` entry
+ * — the server rejects the manifest at submit without one — and expect the
+ * viewer to be prompted to grant it before the first call succeeds.
+ *
+ * 🔴 THE SCOPE GRANT IS NOT THE CONSENT. Every call additionally opens a
+ * host-chrome confirm, and what that confirm shows is the SERVER'S resolution of
+ * your request, never your strings: the tag names that will ACTUALLY be applied,
+ * host-fetched model and version names for a gallery attach, and real
+ * thumbnails. A block cannot show one post and publish another.
+ *
+ * 🔴 NO ARM OF `sources` TAKES A URL. Name a workflow from this app's own
+ * subqueue plus indexes into its outputs, or `Image` ids from a previous
+ * `usePublishGenerationOutputs()` publish. The server re-verifies both.
+ *
+ * ⚠️ POSTING A PUBLISHED IMAGE REMOVES IT FROM THIS APP'S OWN GRID. The
+ * app-scoped read behind `useGatedImages()` is conjoined with `postId IS NULL`,
+ * so an image that joins a post stops resolving there. An app cannot both keep
+ * an image in its shared grid and let the viewer post it.
+ *
+ * Because the reply waits on a person, the request carries
+ * {@link HUMAN_INTERACTION_TIMEOUT_MS} (10 min) rather than the ~30s protocol
+ * default — it resolves the instant the viewer acts, and the ceiling only bounds
+ * an abandoned dialog.
+ *
+ * @example
+ * const { createPost, pending } = useCreatePostFromApp();
+ * const { requestSignIn } = useRequestSignIn();
+ *
+ * const share = async () => {
+ *   try {
+ *     const post = await createPost({
+ *       sources: [{ kind: 'workflow', workflowId: w.workflowId, imageIndexes: [0, 2] }],
+ *       title: 'Made with Sticker Studio',
+ *     });
+ *     showToast(`Posted! ${post.url}`);
+ *   } catch (e) {
+ *     if (e instanceof CreatePostError) {
+ *       if (e.signInRequired) return requestSignIn();
+ *       if (e.declined) return;                    // the viewer said no — say nothing
+ *       if (e.timedOut) return showToast('Still working — check your profile.');
+ *       showToast(e.message);                      // a real server message, safe to render
+ *     }
+ *   }
+ * };
+ */
+export function useCreatePostFromApp() {
+    const [pending, setPending] = useState(false);
+    const [error, setError] = useState(null);
+    // Same guard as `useCollectionFollow`: this request can outlive the component
+    // by up to ten minutes (the viewer may leave the confirm open), so a `pending`
+    // toggled on an unmounted control is state nobody can clear.
+    const mountedRef = useRef(true);
+    useEffect(() => {
+        mountedRef.current = true;
+        return () => {
+            mountedRef.current = false;
+        };
+    }, []);
+    const createPost = useCallback(async (args) => {
+        if (mountedRef.current) {
+            setPending(true);
+            setError(null);
+        }
+        try {
+            const reply = await sendTypedRequest(getTransport(), {
+                type: 'CREATE_POST_FROM_APP',
+                payload: {
+                    sources: args.sources,
+                    ...(args.title !== undefined ? { title: args.title } : {}),
+                    ...(args.detail !== undefined ? { detail: args.detail } : {}),
+                    ...(args.tags !== undefined ? { tags: args.tags } : {}),
+                    ...(args.modelVersionId !== undefined
+                        ? { modelVersionId: args.modelVersionId }
+                        : {}),
+                },
+            }, 'CREATE_POST_RESULT', 
+            // See the `'human'` bucketing in `internal/requestTimeouts.ts`: the
+            // host answers only when the viewer clicks or dismisses its confirm.
+            { timeoutMs: HUMAN_INTERACTION_TIMEOUT_MS });
+            if (reply.error || !reply.result) {
+                // 🔴 `||`, NOT `??`. `isValidCreatePostResult` gates `error` on SHAPE
+                // only (it has to: the channel carries free-text server messages), so
+                // a host `error: ''` is a VALID reply that reaches here. `??` would
+                // then throw an Error with an EMPTY message for a public post, which
+                // renders as a blank failure. Fall through to a code that at least
+                // names a real outcome.
+                throw new CreatePostError(reply.error || 'no images to post');
+            }
+            return reply.result;
+        }
+        catch (err) {
+            // A transport timeout arrives as a plain Error; wrap it so callers have
+            // ONE error type to test, with `.code` left undefined (it is not a host
+            // refusal). Re-wrapping our own error would lose `.code`, so pass it
+            // through.
+            const wrapped = err instanceof CreatePostError
+                ? err
+                : new CreatePostError(err instanceof Error ? err.message : String(err), {
+                    // Structural, not a message match — see `RequestTimeoutError`.
+                    timedOut: err instanceof RequestTimeoutError,
+                });
+            if (mountedRef.current)
+                setError(wrapped);
+            // 🔴 THROWN UNCONDITIONALLY, even when unmounted. The caller's `await`
+            // is not the component — an app that persists the result must still
+            // learn the write failed, and swallowing it here would make an unmount
+            // look like a success.
+            throw wrapped;
+        }
+        finally {
+            if (mountedRef.current)
+                setPending(false);
+        }
+    }, []);
+    return { createPost, pending, error };
+}
+//# sourceMappingURL=useCreatePostFromApp.js.map

package/dist/hooks/useCreatePostFromApp.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useCreatePostFromApp.js","sourceRoot":"","sources":["../../src/hooks/useCreatePostFromApp.ts"],"names":[],"mappings":"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"}