@kody/alexa

@kody/alexa

Head-start stub for an Alexa custom skill whose HTTPS endpoint is a Kody webhook. Alexa calls into Kody. From there you can propagate the utterance. This stub checks a skill application id when you configure one, maps the common request types, and speaks a clear "not wired yet" reply. It does not call alexaForwardUrl.

Intent

Give Alexa a way to call into Kody and propagate from there. A custom skill sends each request to a Kody webhook named skill. This package is the general starting point: it accepts the skill request, checks an optional skill id, and returns normal Alexa response JSON. Success for this stub is an Alexa simulator request that comes back as that JSON and says forwarding is not wired yet. It is not a finished bridge. Signature verification is not implemented, and the reserved forward URL is never called.

When to use

Use this package when an Alexa custom skill should land in Kody so a later step can propagate the utterance (another package, a job, or the reserved forward URL).

Use ./skill-request for the live endpoint and for a local dry run. Use ./verify when you need the written status of signature checking (it is still a TODO).

Do not use this package as a production voice bridge. Signature verification is not implemented, and alexaForwardUrl is never called.

Setup

1. In the Alexa developer console, create a custom skill and an interaction model. A useful first intent is something like Ask with one AMAZON.SearchQuery slot named query. Built-in AMAZON.FallbackIntent also works. The stub echoes slot values and does not require a particular intent name.
2. After publish, mint the webhook named skill (bound to ./skill-request, responseMode: sync). Copy the URL from the package settings Webhooks section. Agents can mint a handle with webhookUrlMint (kodyId: "@kody/alexa", package_scope: "kody", webhookName: "skill") but the credential URL stays on that settings page. Do not paste the URL into chat.
3. In the skill's endpoint setting, choose HTTPS and paste that minted URL. Alexa must get the skill response in the HTTP body, which is why the webhook is sync rather than ack.
4. Optional secrets, created in the Kody secret store (names only; do not invent or commit values):
   • alexaSkillApplicationId: the skill id from the Alexa console, shaped like amzn1.ask.skill.... When this secret is set, live requests must present the same id on session.application.applicationId (or context.System.application.applicationId). A mismatch ends the session with a spoken refusal. When it is unset, the stub still answers and says the secret is not set.
   • alexaForwardUrl: reserved for a later hop that would POST the utterance onward from Kody. This stub never requests that URL. If the secret is set, speech says so and still does not call it.
5. In the Alexa simulator, launch the skill. You should hear that the stub is ready and that forwarding is not wired yet. An intent with a slot should echo the words you said.

dryRun: true or allowUnsigned: true on a direct call skips the application id gate. Both are unsafe for production. The webhook path cannot see Alexa's Signature or SignatureCertChainUrl headers, because Kody's webhook header allowlist does not include them, so crypto verification cannot run in-handler today.

Package list mark: .kody/icon.png is the official Alexa Smile wordmark (Alexa Blue) from Amazon's Alexa Auto design assets on developer.amazon.com, composed square on white for the catalog. Amazon, Alexa and all related logos are trademarks of Amazon.com, Inc. or its affiliates. Logo use for product identification in this developer-tool listing follows Kent's standing preference for official service marks; Amazon's brand guidelines generally require program membership / approval for marketing use — see https://developer.amazon.com/en-US/alexa/branding/alexa-guidelines/brand-guidelines/the-alexa-logo

Done when

• A LaunchRequest returns { version: "1.0", response.outputSpeech, response.shouldEndSession } and the speech says forwarding is not wired yet.
• An IntentRequest echoes the slot text the same way.
• A SessionEndedRequest returns an empty speech response with shouldEndSession: true.
• With alexaSkillApplicationId set, a different application id is refused.
• ./verify still reports implemented: false and unsafeForProduction: true.

Secrets