Skip to main content

Usage Examples

Three concrete paths through cogs, from a Claude Code skill trigger to a typed API call to a signed email send.

1. Trigger a skill in Claude Code​

Once the cogs plugin is installed (see Getting Started), skills activate automatically when a prompt matches their trigger conditions — no manual invocation needed:

> Add a paginated, filterable table of orders to this page, and make the
> filters shareable via URL.

This matches nuqs-table-url-state's trigger conditions and the skill loads into context, steering the implementation toward createTableUrlState instead of a hand-rolled useState + useEffect pagination hook. See the Skills Catalog for what each of the 5 skills triggers on.

2. Typed API calls with @cogs/fetch-client + @cogs/react-query​

@cogs/fetch-client is the transport seam Kubb-generated clients compile against; @cogs/react-query is the single TanStack Query seam every generated hook imports from. Configure the transport once at app bootstrap:

import { configureClient } from '@cogs/fetch-client'

configureClient({
  baseUrl: process.env.NEXT_PUBLIC_API_URL!,
  getToken: () => supabase.auth.getSession().then((s) => s.data.session?.access_token),
})

Then build the query client every generated hook runs through:

import { createQueryClient } from '@cogs/react-query'

const queryClient = createQueryClient({
  onUnauthorized: () => signOutAndRedirect(),
  staleTime: 60_000,
})

Every Kubb-generated useXyzQuery/useXyzMutation hook now shares one retry policy, one 401/403 handler, and one stable cache-key hash — see the kubb-react-query skill if you're setting up the codegen step that produces those hooks in the first place.

3. Send a transactional email via @cogs/auth-events + send-service​

send-service is the single service holding SES credentials; every caller signs its request body with a brand-scoped HMAC secret instead of talking to SES directly. @cogs/auth-events wraps that signing + send for the new-device-login email:

import { sendNewDeviceEmail } from '@cogs/auth-events'

await sendNewDeviceEmail(
  {
    event: 'new_device_login',
    brand: 'workloom',
    to: user.email,
    data: { deviceLabel: 'Chrome on macOS', location: 'Denver, CO', occurredAt: new Date().toISOString() },
  },
  { endpoint: process.env.SEND_SERVICE_URL!, secret: process.env.SEND_SERVICE_SECRET! },
)

Internally this serializes the body once, signs it with HMAC-SHA256 over "<timestamp>.<rawBody>", and POSTs to send-service's /send route with the signature and timestamp as headers — so the exact bytes that were signed are the exact bytes verified, with a timestamp window guarding against replay.