@jpfi/stories

Create personalized Teddy & Pinguin bedtime stories for your child and get the finished text back.

README.md

58 lines · 3.4 KB · Markdown

@jpfi/stories

Intent

This package lets a parent ask a Kody host for a Teddy & Pinguin bedtime story and get the finished German or English text back. Success is readable prose plus a link to the story in their own Teddy library.

Each caller connects their own Teddy & Pinguin account with a personal access token stored in Kody as teddyPinguinToken. Stories are created in that account and count against that account's story quota.

Setup

Create an account at https://www.teddy-pinguin.com and verify your email.
Open API tokens (/de/account/api-tokens) and create a token labeled Kody.
Save it in Kody at /account/secrets/new?name=teddyPinguinToken&allowedHosts=www.teddy-pinguin.com. Never paste the token into a chat.
Approve www.teddy-pinguin.com as an outbound host for the secret.
Confirm with check-connection before your first story.

Exports

Export	Purpose
`check-connection`	Verify the stored token reaches a Teddy account. Read-only, no quota cost.
`generate-story`	Create a story from an idea and wait for the finished prose. Optional `series` or `continueFromStoryId` writes the next episode.
`get-story-result`	Pick up a story that was still being written when `generate-story` returned.

Every export returns a tagged result. It never throws for an expected condition. Branch on status.

`status`	What happened	What to do
`ready`	Accepted prose is in `story`	Read it aloud. Link `story.libraryUrl`.
`pending`	Still being written. The run continues server-side.	Say `nextStep`. Call `get-story-result` later.
`declined`	Teddy's Reviewer said no, or the run was cancelled.	Offer to rephrase if `canRetry`.
`unavailable`	Quota used up, rate limited, or generation failed.	Wait `retryAfterSeconds`, or check the account.
`disconnected`	The token is missing, revoked, or expired.	Send the human to `tokenSetupUrl`.
`invalid_input`	`storyIdea` or `runId` is unusable.	Fix `field` and call again.

Same request for 30 minutes

If you already have a runId from a pending result, call get-story-result. Do not call generate-story again for that request.

If the host lost the runId and submits the same storyIdea, contentLocale, and targetReadMinutes within 30 minutes, Teddy reattaches to the run already in flight. The Idempotency-Key is derived from those fields plus optional series identity, the API origin, and a 30-minute time bucket. It is unique per Teddy user, so two parents with the same idea do not collide.

To get a different story, change the idea. After 30 minutes the same words produce a new story.

Length, locale, and wait

contentLocale defaults to "de".
targetReadMinutes defaults to 8 and is clamped into Teddy's supported 5–12 range.
maxWaitSeconds defaults to 300 and is capped at 360. A story that is still unfinished when the budget runs out returns pending with a runId. maxWaitSeconds: 0 performs exactly one status check.

Optional preview override

Set package storage key apiBaseUrl to an https:// origin to point at a Vercel preview deployment. The teddyPinguinToken secret must also list that host under its allowed hosts. Production default is https://www.teddy-pinguin.com.

Name

Published as @jpfi/stories.

Canonical source is integrations/kody-stories/ in the teddy-pinguin repository.