Nestling - Smart Baby Tracker

Acompanhe as mamadas, o sono, as fraldas e os marcos do seu bebê pelo seu assistente de IA.

Documentação

nestling-ts

Cliente TypeScript, CLI e servidor MCP para o aplicativo de rastreamento de bebês Nestling. Leia e registre dados de sono, alimentação, fraldas e diário da sua conta Nestling — a partir do terminal, de uma biblioteca TypeScript/Bun ou via um servidor Model Context Protocol para Claude, ChatGPT e outros assistentes de IA.

Escritas apenas de criação. A API pode registrar novas entradas que sincronizam com seu aplicativo. Ela não pode atualizar ou excluir entradas existentes — seus dados estão sempre seguros.

Requisitos

Bun 1.3+ — o pacote é distribuído como código-fonte TypeScript sem etapa de build, portanto deve ser executado no Bun (não no Node).
Uma conta Nestling (login com Google ou Apple)
Um token de API da Nestling (gere um no aplicativo: Configurações → Dados → Token de API)

Instalação

Do npm:

bun add -g nestling-ts
# provides `nestling` and `nestling-mcp`

# or add it to a project as a library
bun add nestling-ts

De um checkout do código-fonte:

cd nestling-ts
bun install
bun link          # makes `nestling` available globally

CLI

Início rápido

nestling login
# API Token: (from Nestling app → Settings → Data → API Token)
# Timezone: Europe/London
# ✓ Authenticated as you@example.com! Found 1 child(ren).

nestling babies
# • Eloise (id: abc-123)  8 months old

Se você ainda não executou o bun link, use o script do pacote:

bun run --cwd /path/to/nestling-ts nestling -- login
bun run --cwd /path/to/nestling-ts nestling -- babies

Comandos

# Sleep
nestling sleep history --days 3
nestling sleep log --start "yesterday 8pm" --end "today 6:30am"
nestling sleep log --start 2026-05-07T20:00:00Z --end 2026-05-08T06:30:00Z

# Feed
nestling feed history --days 2
nestling feed log --at "now" --type Bottle --amount 180
nestling feed log --at "30m ago" --type Breastfeeding --side Left

# Nappy
nestling nappy history --days 2
nestling nappy log --at "5 minutes ago" --type Wet

# Diary
nestling diary history --days 7
nestling diary log --at "today 3pm" --text "First time clapping!" --tags milestone,funny

# Multiple babies
nestling --baby "Eloise" sleep history

Todos os comandos history suportam --json para saída legível por máquina. A flag --baby seleciona uma criança específica por nome ou ID (o padrão é o primeiro bebê).

Formatos de hora

Todos os argumentos de hora aceitam formatos flexíveis e amigáveis:

Formato	Exemplo
ISO 8601	`2026-05-07T20:00:00Z`
Data + hora	`2026-05-07 8pm`, `2026-05-07 20:00`
Dia relativo	`today 3pm`, `yesterday 8:30pm`, `tomorrow 7am`
Somente hora (hoje)	`3pm`, `3:30pm`, `15:30`
Relativo	`now`, `5 minutes ago`, `2 hours ago`, `30m ago`

As horas são resolvidas usando seu fuso horário configurado (variável de ambiente NESTLING_TIMEZONE ou timezone em ~/.config/nestling/config.json).

Autenticação

A configuração é armazenada em ~/.config/nestling/config.json.

Login interativo: nestling login
Variáveis de ambiente (têm precedência sobre o arquivo de configuração):
- NESTLING_API_TOKEN
- NESTLING_TIMEZONE (opcional)

Uso da biblioteca

import { Nestling } from "nestling-ts";

const client = new Nestling({
  apiToken: process.env.NESTLING_API_TOKEN!,
});

// Authenticate
await client.signIn();

// Account & babies
const user = await client.getUser();
const babies = await client.babies.list();
const baby = await client.babies.get(babies[0].id);

// History (all take a DateRange)
const range = {
  start: new Date("2026-05-01T00:00:00Z"),
  end: new Date("2026-05-08T00:00:00Z"),
};
await client.sleep.list(baby.id, range);
await client.feed.list(baby.id, range);     // breast | bottle | solids | expressing
await client.nappies.list(baby.id, range);  // wet | dirty | both
await client.diary.list(baby.id, range);    // journal entries & milestones

// Log new entries
await client.sleep.create(baby.id, {
  start: "2026-05-07T20:00:00Z",
  end: "2026-05-08T06:30:00Z",
});

await client.feed.create(baby.id, {
  timestamp: "2026-05-07T12:00:00Z",
  type: "Bottle",
  amountMl: 180,
});

await client.nappies.create(baby.id, {
  timestamp: "2026-05-07T14:00:00Z",
  type: "Wet",
});

await client.diary.create(baby.id, {
  timestamp: "2026-05-07T15:00:00Z",
  text: "First time clapping!",
  tags: ["milestone"],
});

await client.close();

Compatibilidade com a nuvem

nestling-ts mantém nomes de interface ergonômicos enquanto grava o modelo de nuvem compatível com iOS. Por exemplo, amountMl e durationSeconds são aceitos por client.feed.create() e armazenados no Supabase como chaves de payload de alimentação amount e duration. Os payloads de entrada são gravados como JSON stringificado em entries.data para corresponder à implementação de sincronização do iOS atual.

Ao adicionar novas ferramentas ou gravadores diretos no Supabase, siga o formato canônico de entrada de linha do README raiz. Em particular, use valores de alimentação Breastfeeding, Bottle, Solids, Expressing; valores de fralda Wet, Dirty, Both; e valores de sono source manual ou timer.

Servidor MCP

nestling-ts inclui um servidor MCP como o binário nestling-mcp. Ele encapsula a biblioteca como um conjunto de ferramentas MCP que qualquer agente de IA pode chamar — incluindo Claude, ChatGPT e outras interfaces de LLM que suportam MCP.

O servidor suporta dois modos de transporte:

stdio (padrão) — para uso local com Claude Desktop, Claude Code, Cursor, etc.
HTTP (--http) — transporte remoto Streamable HTTP para conectores personalizados do Claude, conectores personalizados do ChatGPT ou qualquer cliente compatível com MCP pela rede.

Claude Desktop / Claude Code (stdio)

Aponte para o checkout do código-fonte:

{
  "mcpServers": {
    "nestling": {
      "command": "bun",
      "args": ["run", "nestling-mcp"],
      "cwd": "/absolute/path/to/nestling-ts",
      "env": {
        "NESTLING_API_TOKEN": "your-token-from-nestling-app",
        "NESTLING_TIMEZONE": "Europe/London"
      }
    }
  }
}

Observação: o comando deve ser bun/bunx — não node/npx. O pacote é publicado como TypeScript puro, que o Bun executa diretamente.

Conector personalizado do Claude (MCP remoto / modo HTTP)

Hospedado (mais simples — sem necessidade de configuração):

No Claude, vá para Personalizar → Conectores → Adicionar conector personalizado (Pro/Max) ou peça ao proprietário da organização para adicioná-lo (Team/Enterprise).
Defina URL para https://mcp.nestling-app.com/mcp e clique em Adicionar.
O Claude abre uma página de login — cole seu token de API da Nestling em Configurações → Dados → Token de API.
Pronto. O Claude agora pode ler e registrar os dados do seu bebê.

Sem ngrok, sem portas, sem auto-hospedagem. Cada usuário autentica com seu próprio token via OAuth.

Auto-hospedado:

Execute o servidor MCP em modo HTTP você mesmo:

# Single-user (token from env)
export NESTLING_API_TOKEN="your-token"
bun run nestling-mcp -- --http
# Nestling MCP server (HTTP) listening on http://localhost:8787/mcp

# Multi-user (no env token; each request authenticates via Bearer header)
bun run nestling-mcp -- --http
# Users pass their own token as Authorization: Bearer <token>

Defina uma porta personalizada com PORT=3000 bun run nestling-mcp -- --http.

Para acesso público, coloque o servidor atrás de HTTPS (Cloudflare Tunnel, nginx, etc.) — o Claude se conecta pela nuvem da Anthropic, então localhost não funcionará.

Conector personalizado do ChatGPT

O ChatGPT suporta servidores de ferramentas MCP como conectores personalizados no GPT Builder. Use o endpoint hospedado ou execute o seu próprio:

Use a URL hospedada ou execute bun run nestling-mcp -- --http em um servidor.
No ChatGPT GPT Builder → Actions → "Add action".
Defina a URL do servidor para o seu endpoint /mcp.
Defina a autenticação como Bearer e cole seu token de API da Nestling.
O ChatGPT descobrirá as ferramentas automaticamente via protocolo MCP.

Ferramentas

Ferramenta	Propósito
`get_capabilities`	Descoberta: quais fontes de dados e ferramentas estão disponíveis
`get_user`	Perfil da conta (e-mail, ID de usuário)
`list_babies`	Lista de bebês (`id` é passado para todas as outras ferramentas)
`get_baby`	Detalhes do bebê (apelido, data de nascimento, etc.)
`list_sleep`	Sessões de sono de um bebê em um intervalo de datas
`list_feeds`	Entradas de alimentação (mama, mamadeira, sólidos) em um intervalo de datas
`list_nappies`	Entradas de fralda em um intervalo de datas
`list_diary`	Entradas de diário em um intervalo de datas
`create_sleep`	Registrar uma nova sessão de sono (hora de início + fim)
`create_feed`	Registrar uma nova alimentação (mama, mamadeira, sólidos, extração)
`create_nappy`	Registrar uma nova troca de fralda
`create_diary`	Registrar uma nova entrada de diário

As ferramentas de leitura retornam dados; as ferramentas de escrita criam novas entradas (sem atualização ou exclusão).

Envelope de resposta

{
  "data": [...],
  "totalResults": 12
}

Envelope de erro

{
  "error": "BabyNotFoundError",
  "message": "Baby not found: abc",
  "category": "not_found",
  "retryable": false,
  "recovery": "Use client.babies.list() (or the list_babies MCP tool) to get valid baby IDs."
}

Segurança

Escritas apenas de criação — a API pode adicionar novas entradas, mas não pode atualizar ou excluir as existentes.
Escopo por usuário — autentica como usuário regular da Nestling via Supabase Auth. A Segurança em Nível de Linha (RLS) garante que você possa acessar apenas seus próprios bebês e dados (além de qualquer coisa compartilhada com você).
Sem chaves de serviço — usa a chave anon do Supabase, não uma chave de papel de serviço. A chave anon pode ser distribuída com segurança; ela apenas permite acesso protegido por RLS.
Remoto local ou auto-hospedado — no modo stdio, as credenciais permanecem na sua máquina. No modo HTTP, cada usuário autentica por sessão com seu próprio token Bearer.
Isolamento por usuário — o servidor HTTP cria uma sessão autenticada separada por token. Os usuários só podem acessar seus próprios dados via RLS do Supabase.
Sessões de curta duração — os JWTs do Supabase expiram após 1 hora e são renovados automaticamente. Seu token de API de longa duração é usado apenas para iniciar a sessão.

Obtendo seu token de API

Abra o aplicativo Nestling no seu telefone.
Vá para Configurações → Dados → Token de API.
Toque em Copiar Token.
Cole o token na configuração do seu MCP ou variáveis de ambiente.

O token está vinculado à sua conta. Você pode revogá-lo a qualquer momento tocando em Token de API novamente — gerar um novo token invalida o antigo.

Referência da API

`new Nestling(options)`

Opção	Tipo	Observações
`apiToken`	`string`	Token de API do aplicativo Nestling

Métodos de leitura

client.babies.list() → Baby[]
client.babies.get(babyId) → Baby
client.sleep.list(babyId, range) → SleepEntry[]
client.feed.list(babyId, range) → FeedEntry[]
client.nappies.list(babyId, range) → NappyEntry[]
client.diary.list(babyId, range) → DiaryEntry[]

Métodos de escrita

client.sleep.create(babyId, input) → string (novo ID de entrada)
client.feed.create(babyId, input) → string
client.nappies.create(babyId, input) → string
client.diary.create(babyId, input) → string

Classes de erro

NestlingError — classe base com category, retryable, recovery
AuthenticationError — credenciais inválidas ou sessão expirada
BabyNotFoundError — ID de bebê desconhecido
InvalidDateRangeError — start >= end, ou entrada que não é Date

Desenvolvimento

bun install
bun link               # register `nestling` and `nestling-mcp` on your PATH
bun test               # run the test suite
bun run lint           # tsc --noEmit
bun run nestling       # run the CLI (e.g. bun run nestling -- babies)
bun run mcp            # start the MCP server locally

Assistentes de voz

Siri

Integrado ao aplicativo iOS — sem necessidade de configuração. Diga coisas como:

"Registrar fralda no Nestling"
"Iniciar sono no Nestling"
"Registrar amamentação no Nestling"
"Registrar mamadeira no Nestling"

Funciona via o aplicativo Atalhos no iOS 16+.

Alexa

O diretório alexa/ contém uma skill auto-hospedada da Alexa que registra alimentações, sono e fraldas por voz. Ela é executada na sua própria conta AWS como uma função Lambda.

Comandos de voz

O que você quer fazer	Diga
Iniciar sono	"Alexa, tell Nestling to start sleep"
Parar sono	"Alexa, tell Nestling to stop sleep"
Pausar / retomar sono	"Alexa, tell Nestling to pause sleep"
Registrar fralda molhada	"Alexa, tell Nestling to log a wee nappy"
Registrar fralda suja	"Alexa, tell Nestling to log a poo nappy"
Registrar fralda molhada e suja	"Alexa, tell Nestling to log a wet and dirty nappy"
Iniciar amamentação	"Alexa, tell Nestling to start nursing"
Trocar de lado	"Alexa, tell Nestling to switch sides"
Parar amamentação	"Alexa, tell Nestling to stop nursing"
Registrar mamadeira	"Alexa, tell Nestling to log a 120 ml bottle"
Registrar sólidos	"Alexa, tell Nestling to log sweet potato"
Último sono	"Alexa, ask Nestling for the last sleep"
Última alimentação	"Alexa, ask Nestling for the last feed"
Última fralda	"Alexa, ask Nestling for the last nappy"

Tanto nappy/diaper quanto wee/pee são aceitos.

Pré-requisitos

Conta AWS com permissões para implantar pilhas CloudFormation e funções Lambda
Conta de desenvolvedor Alexa (gratuita)
Conta Nestling com pelo menos um bebê adicionado
Seu token de API do aplicativo Nestling (Configurações → Dados → Token de API para Acesso de IA)
Node.js 20+ e npm
SAM CLI

Implantação

cd alexa
npm install
npm run build
sam build
sam deploy --guided

O SAM solicitará:

Parâmetro	Descrição	Exemplo
`NestlingApiToken`	Token de API do aplicativo	(string base64)
`Timezone`	Fuso horário IANA para horários falados	`Europe/London`

Após a implantação da pilha, copie o ARN da Lambda das saídas.

Conectar à Alexa

Abra o Console de Desenvolvedor Alexa
Crie uma nova skill Custom (escolha hospedagem "Provision your own")
Vá para Build → Interaction Model → JSON Editor
Cole o conteúdo de alexa/skill/interactionModel.json
Em Endpoint, selecione AWS Lambda ARN e cole seu ARN da Lambda
Clique em Save Model, depois em Build Model
Teste no simulador da Alexa ou no seu dispositivo

Atualização

Após alterações de código ou um novo token de API:

cd alexa && npm run build && sam build && sam deploy

Segurança

Seu token de API é armazenado como uma variável de ambiente criptografada da Lambda (NoEcho)
Ele nunca é registrado em logs nem incluído nas respostas da Alexa
Todas as consultas ao Supabase passam pela Segurança em Nível de Linha — o token só pode acessar seus próprios dados

Limitações

Somente criação. Não há atualização ou exclusão. Novas entradas sincronizam com o aplicativo automaticamente.
Somente Bun. A CLI e a biblioteca exigem Bun. A skill da Alexa usa Node.js (implantada como Lambda).

Licença

MIT