@elevasis/sdk 1.51.0 → 1.52.0

package/reference/scaffold/recipes/extend-content.md

@@ -51,23 +51,30 @@ A pipeline's step catalog is named `content:catalog/{pipelineId}-steps` and refe
 | Add content nav or a content route                | `CONTENT_ITEMS`, `ContentSidebar`, `ContentSidebarMiddle`                         | Same manifest/sidebar composition pattern as CRM and lead-gen.                                              |
 | Give producers a style guide or voice constraints | The generating workflow's own prompt                                              | Content has no rules-document tier. Put the instructions where the model reads them.                        |
 | Track where a piece was published                 | `createDistribution` / `updateDistribution`                                       | One distribution row per platform per item.                                                                 |
+| Actually post an item to a platform               | Section 6 — a publish panel of yours, over a prepared distribution row            | Publishing is operating, so it is your screen. Instagram has a published workflow; do not copy it.          |
 | Pick source material for a new item               | `createSourceAsset` / `getSourceAsset` / `listSourceAssets` / `updateSourceAsset` | Raw material a producer works from -- an uploaded episode, a transcript, a reference file.                  |
 | Operate the pipeline from outside a browser       | `elevasis-sdk content:*`                                                          | Read-only plus one write (`content:review`). Not how a workflow produces content -- see the boundary below. |
 | Add a new persisted content column or table       | Platform/API migration work, not just scaffold work                               | DB, core schemas/types, API service/handlers, hooks, docs, and scaffold contracts move together.            |
 
 ## Published Content Surfaces
 
-| Surface                                                                                                                | Import from                     | Use for                                          |
-| ---------------------------------------------------------------------------------------------------------------------- | ------------------------------- | ------------------------------------------------ |
-| `contentManifest`, `CONTENT_ITEMS`, `ContentSidebar`, `ContentSidebarMiddle`, `MyReviewQueuePanel`                     | `@elevasis/ui/features/content` | Feature registration and sidebar composition     |
-| `ContentOverviewPage`, `ContentItemsPage`, `ContentItemReviewPage`, `ContentPipelinesPage`, `ContentPipelineBoardPage` | `@elevasis/ui/features/content` | Shared pages you can route to or wrap            |
-| `ContentDistributionsPage`, `ContentDistributionDetailPage`                                                            | `@elevasis/ui/features/content` | Distribution surfaces                            |
-| `ContentReviewCard`, `ReviewActionBar`, `PayloadBody`, `AlternatesPanel`, `ProcessingStateStrip`                       | `@elevasis/ui/features/content` | Review UI primitives for a custom review screen  |
-| `useContentConfig`, `resolveContentStepResource`                                                                       | `@elevasis/ui/features/content` | Read the resolved pipeline/step catalogs from OM |
-| `useContentItems`, `useContentItem`, `useContentItemAttempts`, `useUpdateContentItem`, `useReviewContentItem`          | `@elevasis/ui/hooks`            | Item data access and review mutations            |
-| `useContentDistributions`, `useContentDistribution`, `useUpdateContentDistribution`                                    | `@elevasis/ui/hooks`            | Distribution data access                         |
-| `useContentPipelineSummary`                                                                                            | `@elevasis/ui/hooks`            | Pipeline roll-ups                                |
-| `content`                                                                                                              | `@elevasis/sdk/worker`          | Workflow-side content adapter                    |
+| Surface                                                                                                                | Import from                         | Use for                                          |
+| ---------------------------------------------------------------------------------------------------------------------- | ----------------------------------- | ------------------------------------------------ |
+| `contentManifest`, `CONTENT_ITEMS`, `ContentSidebar`, `ContentSidebarMiddle`, `MyReviewQueuePanel`                     | `@elevasis/ui/features/content`     | Feature registration and sidebar composition     |
+| `ContentOverviewPage`, `ContentItemsPage`, `ContentItemReviewPage`, `ContentPipelinesPage`, `ContentPipelineBoardPage` | `@elevasis/ui/features/content`     | Shared pages you can route to or wrap            |
+| `ContentDistributionsPage`, `ContentDistributionDetailPage`                                                            | `@elevasis/ui/features/content`     | Distribution surfaces                            |
+| `ContentReviewCard`, `ReviewActionBar`, `PayloadBody`, `AlternatesPanel`, `ProcessingStateStrip`                       | `@elevasis/ui/features/content`     | Review UI primitives for a custom review screen  |
+| `useContentConfig`, `resolveContentStepResource`                                                                       | `@elevasis/ui/features/content`     | Read the resolved pipeline/step catalogs from OM |
+| `useContentItems`, `useContentItem`, `useContentItemAttempts`, `useUpdateContentItem`, `useReviewContentItem`          | `@elevasis/ui/hooks`                | Item data access and review mutations            |
+| `useContentDistributions`, `useContentDistribution`, `useUpdateContentDistribution`                                    | `@elevasis/ui/hooks`                | Distribution data access                         |
+| `useContentPipelineSummary`                                                                                            | `@elevasis/ui/hooks`                | Pipeline roll-ups                                |
+| `ContentWorkspaceShell`, `ContentAnalysisStepPanel`, `ContentStepPanelMap`, `ContentWorkspaceState`                    | `@elevasis/ui/features/content`     | The workspace frame and its panel contract       |
+| `useExecuteAsync`, `useExecution`, `isExecutionInFlight`, `TERMINAL_EXECUTION_STATUSES`                                | `@elevasis/ui/hooks`                | Start a publishing workflow and watch it finish  |
+| `useCreateContentDistribution`, `useUpdateContentDistribution`                                                         | `@elevasis/ui/hooks`                | Prepare and record a post                        |
+| `content`                                                                                                              | `@elevasis/sdk/worker`              | Workflow-side content adapter                    |
+| `createPublishInstagramWorkflow`, `createInstagramAdapter`                                                             | `@elevasis/sdk/worker`              | Post to Instagram from a workflow                |
+| `createMockInstagram`                                                                                                  | `@elevasis/sdk/test-utils`          | Test a publish pipeline without a real account   |
+| `defineContentPipeline`, `defineContentSystem`                                                                         | `@elevasis/core/organization-model` | Declare a pipeline and derive the System block   |
 
 Read the generated contracts before changing typed boundaries:
 
@@ -418,13 +425,254 @@ rendering "Pipelines" here, and nothing fails to tell you.
 Replace `contentManifest` with `customContentManifest` in the local `SYSTEM_MANIFESTS` array and add
 the matching route under `ui/src/routes/content/`.
 
-## 6. Mark the System API-Ready
+## 6. Send It Out
+
+Sections 1 through 5 get an item made and reviewed. This one covers the last step of a pipeline
+that publishes: turning a finished item into a post on a platform.
+
+Publishing is **operating**, so by the section 5 contract it is yours: a panel on your workspace,
+not a shared page. The shared distribution pages display what went out and never write. What the
+platform gives you is the distribution row, a way to start a workflow and watch it, and — for
+Instagram — the publishing workflow itself.
+
+### A panel is registered against a step key
+
+`ContentWorkspaceShell` walks the pipeline from the deployed model and renders whichever panel
+your map names for the active step. The map is keyed by **step key**, not by any convention on the
+component:
+
+```tsx
+import { ContentAnalysisStepPanel, ContentWorkspaceShell } from '@elevasis/ui/features/content'
+import type { ContentStepPanelMap } from '@elevasis/ui/features/content'
+
+interface PostDraft {
+  platform: string | null
+  publishExecutionId: string | null
+}
+
+const panels: ContentStepPanelMap<PostDraft> = {
+  analysis: ContentAnalysisStepPanel,
+  caption: CaptionStepPanel,
+  publish: PublishStepPanel
+}
+
+export function WritePostPage() {
+  return (
+    <ContentWorkspaceShell
+      panels={panels}
+      initialDraft={{ platform: null, publishExecutionId: null }}
+      title="Write a Post"
+    />
+  )
+}
+```
+
+Every panel is called with the same `ContentWorkspaceState<TDraft>` — the item, its body, the
+distribution row, `refetchDistributions`, step navigation, and your own `draft`. Anything matching
+that signature is a panel. A step key with no entry in the map is reported rather than rendering
+nothing, which is the reason the map is explicit instead of derived from the key.
+
+`ContentAnalysisStepPanel` is the one step panel published today, because it needs an item id and
+nothing else. A publish panel is not shippable the same way: it reaches a credential, a status
+vocabulary, and a workflow id, all of which are yours to choose.
+
+### Prepare the distribution row before posting
+
+A distribution is one row per platform per item, and it is what the publishing workflow reads. It
+must exist, and carry its media, **before** anything goes out:
+
+```tsx
+const createDistribution = useCreateContentDistribution()
+
+await createDistribution.mutateAsync({
+  contentItemId: item.id,
+  platform,
+  format: 'carousel',
+  status: 'pending',
+  // The caption as it will go out. The row is the record of the post, not a pointer at an
+  // item whose body may be edited afterwards.
+  adaptedBody: body.trim().length > 0 ? body : null,
+  mediaUrls: renderedEntries
+})
+refetchDistributions()
+```
+
+The row freezing what goes out is the point: re-cropping an image after the fact must not quietly
+change what the record says was posted. The corollary is that a row prepared before the caption was
+written holds a stale caption — write the current body onto it at post time, while `publishedAt` is
+still null and nothing has gone out yet.
+
+### Reaching a publishing workflow
+
+Start it async and watch it. Staging a carousel is one upload per image plus polling until the
+platform reports each container finished, which is far longer than a request a page can hold open:
+
+```tsx
+const startPublish = useExecuteAsync()
+const publishExecution = useExecution(publishWorkflowId, draft.publishExecutionId ?? '')
+
+const started = await startPublish.mutateAsync({
+  resourceId: publishWorkflowId,
+  resourceType: 'workflow',
+  input: { distributionId: distribution.id }
+})
+setDraft({ publishExecutionId: started.executionId })
+```
+
+**Name the workflow; do not ask the model which one it is.** `resolveContentStepResource` returns
+the first resource whose ontology claims the step's action, which is a coin flip once more than one
+does. A workflow id is a decision your app makes — pass it as a prop or read it from your own
+config.
+
+**Use `isExecutionInFlight` for "is it still going", not `status === 'running'`.** `warning` is a
+terminal status the platform picks for a run that succeeded while emitting warn-level logs, so a
+`running` test treats a finished run as still in flight and a `completed`-only test never notices
+it finished. Both are exported from `@elevasis/ui/hooks`:
+
+```tsx
+import { isExecutionInFlight, TERMINAL_EXECUTION_STATUSES } from '@elevasis/ui/hooks'
+```
+
+`useExecution` already polls on that predicate, so a panel needs no poll of its own. One browser
+caveat when you go to verify it: React Query pauses `refetchInterval` while `document.hidden`, so a
+backgrounded tab measures zero requests against correct code.
+
+### Instagram: use the published workflow, do not copy it
+
+`createPublishInstagramWorkflow` takes a credential name and returns a registered workflow. That is
+the whole of what is project-specific about posting to Instagram:
+
+<!-- doc-snippet:skip: illustrative excerpt -- a project-local registration module -->
+
+```ts
+import { createPublishInstagramWorkflow } from '@elevasis/sdk/worker'
+
+export const publishInstagramWorkflow = createPublishInstagramWorkflow({
+  credentialName: 'acme-instagram',
+  resourceId: 'cnt-publish-instagram-workflow'
+})
+```
+
+The credential holds `{ accessToken, igUserId }` — the account id rides along with the token, so no
+caller carries it. Given a `distributionId` the workflow signs each image, builds the containers,
+publishes, and writes the returned post id and permalink back onto the same row. It does not move
+the item's status: which status means "finished" is resolved against your own model by the surface
+that owns the item, and deciding it twice is two answers that can disagree.
+
+**It refuses rather than repairs, and that is why it is not yours to copy.** Three checks run before
+anything reaches Instagram, each guarding an action that cannot be taken back:
+
+| Refusal                                  | Why it is a refusal                                                         |
+| ---------------------------------------- | --------------------------------------------------------------------------- |
+| the row's `platform` is not `instagram`  | posting a row prepared for somewhere else posts the wrong thing             |
+| the row already carries `platformPostId` | only a real publish writes that field, so posting again duplicates the post |
+| the row already carries `publishedAt`    | someone recorded this as posted; posting now would post it twice            |
+| the row has no `mediaUrls`               | there is nothing to post — render first                                     |
+
+To post again, create a new distribution. Nothing clears these.
+
+A failed execution therefore generally means **nothing was posted**, and its own error message is
+more specific than anything a panel could write — show `execution.error` rather than a generic line.
+
+### Posting by hand
+
+Not every platform has a workflow behind it, and the manual path needs no credential at all.
+Record it on the same row:
+
+```tsx
+await updateDistribution.mutateAsync({
+  distributionId: distribution.id,
+  updates: {
+    status: 'published',
+    publishMethod: 'manual',
+    publishedAt: new Date().toISOString(),
+    ...(isUsableUrl ? { platformUrl: typedUrl } : {})
+  }
+})
+```
+
+`publishedAt` set with no `platformPostId` is the manual shape — do not invent an id no platform
+returned. When you later ask how a post went out, test against `'manual'` rather than against an
+API value: a publishing workflow writes the platform it posted through (`'instagram-api'`), so
+"was this done by hand" is the question with one stable answer.
+
+### Testing a publish pipeline
+
+Mock the integration; do not point a test at a real account. `createMockInstagram` covers all eight
+adapter methods:
+
+<!-- doc-snippet:skip: illustrative excerpt -- vitest usage inside a project's own suite -->
+
+```ts
+import { createMockInstagram } from '@elevasis/sdk/test-utils'
+
+const instagram = createMockInstagram('acme-instagram', {
+  // A publish sequence polls until the container reports FINISHED. Un-overridden, it never does.
+  getContainerStatus: ({ containerId }) => ({ containerId, statusCode: 'FINISHED', status: 'Finished' }),
+  publishContainer: { mediaId: 'media-1' }
+})
+```
+
+## 7. Mark the System API-Ready
 
 `content.apiInterface.lifecycle` goes `active` only when the System's scoped resources, `content:object/item`, and the pipeline/step/status catalogs are all in place. Two failure modes are worth knowing before you flip it:
 
 - An **empty** `apiInterface.resourceIds` array throws rather than opting out. Omitting the whole `apiInterface` block is the opt-out; a `resourceIds: []` stub is the anomaly.
 - Readiness is derived from a **deployed** snapshot. A model edit that has not been redeployed produces a stale-snapshot 503 that looks like a code bug. Redeploy before debugging.
 
+### Or derive the whole block with `defineContentSystem`
+
+`defineContentPipeline` (section 1) removes the per-pipeline duplication. What is left is the
+surrounding boilerplate every content adopter writes identically: the `apiInterface` block, its
+`readinessContract`, the `content:object/item` object type, and the status catalog. `defineContentSystem`
+takes the pipelines and derives all four.
+
+<!-- doc-snippet:skip: illustrative excerpt -- references project-local pipeline declarations -->
+
+```ts
+import { defineContentPipeline, defineContentSystem } from '@elevasis/core/organization-model'
+
+const linkedInPost = defineContentPipeline({
+  systemPath: 'content',
+  id: 'linkedin-post',
+  label: 'LinkedIn Post',
+  workspaceRoute: '/content/write',
+  steps: [{ key: 'draft', actor: 'agent', review: 'required', resource: saveContentBatch }]
+})
+
+export const contentSystem = defineContentSystem({
+  systemPath: 'content',
+  resourceIds: ['save-content-batch', 'publish-linkedin'],
+  pipelines: [linkedInPost],
+  item: { label: 'Post', description: 'One LinkedIn post, from idea to distribution.' },
+  statuses: [
+    { key: 'draft', label: 'Written', order: 10, semanticClass: 'active' },
+    { key: 'posted', label: 'Posted', order: 20, semanticClass: 'completed' }
+  ]
+})
+
+// Inside the content System:
+//   apiInterface: contentSystem.apiInterface
+//   ontology:     { ...contentSystem.objectTypes, ...contentSystem.catalogTypes, ...yourOwn }
+```
+
+It emits `apiInterface` (with `readinessProfile: 'content.api'` and a `readinessContract` listing
+the pipeline, every step catalog, and the status catalog), `objectTypes` carrying
+`content:object/item`, and `catalogTypes` carrying the pipeline, step, and status catalogs. Your own
+object types, action types, and per-adopter catalogs — pillar, platform, source-asset kind — stay
+hand-authored alongside them.
+
+**The contract is unchanged; only the boilerplate is gone.** Content is validated against a
+declared `readinessContract` rather than a platform validator, and that is deliberate: a CRM
+pipeline is a CRM pipeline, so platform code can hardcode what to check, while a content pipeline is
+whatever its adopter declares. Making it built-in would hardcode one step catalog for every project.
+`defineContentSystem` writes the contract for you; it does not remove it.
+
+**`lifecycle` defaults to `'active'`, so calling this helper is itself the decision to serve the
+API.** Pass `lifecycle: 'draft'` while the pipelines are declared but not yet served. The opt-out
+above — omitting `apiInterface` entirely — means not calling `defineContentSystem` for that block at
+all; there is no way to call it and get no marker.
+
 ## Verify
 
 Run the checks for the surfaces you touched:

package/reference/ui/exports.mdx

@@ -56,7 +56,6 @@ description: "Auto-generated catalog of all published @elevasis/ui subpath expor
 | `@elevasis/ui/provider/ElevasisServiceContext` | Elevasis Service Context | Provider | Standalone service context and provider that supplies apiRequest, organizationId, and isReady to child components. |
 | `@elevasis/ui/hooks/delivery` | Hooks Delivery | Hooks | Published delivery hooks for projects, milestones, tasks, and notes. |
 | `@elevasis/ui/hooks/user-notes` | Hooks User Notes | Hooks | Published user-notes query and mutation hooks used by shared Notes surfaces. |
-| `@elevasis/ui/hooks/operations/command-view/utils/transformCommandViewData` | Transform Command View Data | Hooks | Utility that transforms backend CommandViewData arrays into a unified frontend CommandViewGraph with nodes and edges. |
 | `@elevasis/ui/test-utils` | Test Utils | Testing | Published rendering helpers, auth mocks, MSW handlers, and test provider utilities. |
 | `@elevasis/ui/test-utils/setup` | Test Utils Setup | Testing | Vitest setup file for UI consumers using browser mocks and MSW. |
 | `@elevasis/ui/test-utils/setup-integration` | Test Utils Integration Setup | Testing | Vitest setup file for integration tests that avoid MSW and use real network boundaries. |