# @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

| Name | Required | What it is |
| --- | --- | --- |
| `alexaSkillApplicationId` | No for the stub, yes before you trust live traffic | Alexa skill application id |
| `alexaForwardUrl` | No | Future forward target. Not called. |