Librerie

Le librerie di Blupinta chiamano l’API pubblica per te: l’accesso su auth.blupinta.app, ogni operazione con i suoi tipi, una casa seguita man mano che se ne salvano le versioni. Parlano solo con l’API: i controlli di una casa sono quelli di Blupinta, chiesti con POST /v1/homes/check. I loro sorgenti sono pubblici, su github.com/blupinta/blupinta, con licenza Apache 2.0. Gli esempi qui sotto sono quelli che i controlli delle librerie compilano, quindi funzionano così come sono scritti.

TypeScript: @blupinta/sdk

Per il browser e per Node: ogni operazione chiamata per nome (client.call('getHome', …)), con parametri e risposta tipizzati; un rifiuto è un BlupintaError con il code dell’API; watchHome mostra la copia tenuta sul dispositivo, poi ogni versione nuova.

npm install @blupinta/sdk

quickstart.ts

// A dashboard's first lines with @blupinta/sdk: connect with a code typed on a phone, then show the home and follow
// each new version. Typechecked with the package, so it can't drift from it.
import { createClient } from '@blupinta/sdk'
import { startDeviceSignIn, tokenKeeper } from '@blupinta/sdk/auth'
import { memoryHomeStore, watchHome } from '@blupinta/sdk/watch'

const signIn = await startDeviceSignIn({ scope: 'openid offline_access projects:read' })
console.log(`Open ${signIn.verificationUri} and type ${signIn.userCode}`)
const tokens = await signIn.tokens()

const client = createClient({ token: tokenKeeper({ clientId: 'device', tokens }) })
const { rows } = await client.call('listProjects')
const project = rows[0]
if (!project) throw new Error('no project was chosen')

watchHome(client, project.id, {
  store: memoryHomeStore(),
  onHome: (saved) => console.log(`${saved.home.name}: version ${saved.number}`),
  onError: (error) => console.error(error.code, error.problems),
})

React: @blupinta/react

useHome, useProject e useRevisions dentro un BlupintaProvider, e useSignIn per l’accesso dal browser con PKCE, che si conclude da solo sull’indirizzo di ritorno della tua app (Registrarla).

Quickstart.tsx

// A page with @blupinta/react: sign in with Blupinta, then show a home that updates as versions are saved.
// Typechecked with the package, so it can't drift from it.
import { useHome } from '@blupinta/react/hooks'
import { BlupintaProvider } from '@blupinta/react/provider'
import { useSignIn } from '@blupinta/react/sign-in'
import { createClient } from '@blupinta/sdk'
import { useMemo } from 'react'

export function App() {
  const session = useSignIn({
    clientId: 'app_…', // registered in Blupinta's settings, Developers
    redirectUri: 'https://your.app/', // one of its return addresses: this page finishes the sign-in
    scope: 'openid offline_access projects:read',
  })
  const client = useMemo(() => createClient({ token: session.token }), [session.token])
  if (!session.tokens)
    return (
      <button type="button" onClick={session.signIn}>
        Sign in with Blupinta
      </button>
    )
  return (
    <BlupintaProvider client={client}>
      <Home projectId="…" />
    </BlupintaProvider>
  )
}

function Home({ projectId }: { projectId: string }) {
  const { data, error, isLoading } = useHome(projectId)
  if (isLoading) return <p>Loading…</p>
  if (error) return <p>{error.code}</p>
  return (
    <h1>
      {data?.home.name}, version {data?.number}
    </h1>
  )
}

La riga di comando: blupinta

npx @blupinta/cli login                    # un codice scritto nel browser; i token nel portachiavi
npx @blupinta/cli pull "Casa" --dir casa    # home.json e i suoi file
npx @blupinta/cli check casa/home.json      # i controlli di Blupinta sul file
npx @blupinta/cli push --dir casa -m "Spostato il divano"
npx @blupinta/cli watch "Casa" --exec "./ridisegna.sh"

Ogni comando accetta --json, per script e agenti. Un push fatto su una versione vecchia viene rifiutato, dicendo chi ha salvato dopo.

Agenti AI: @blupinta/mcp

Un server MCP: un agente elenca i progetti, legge una casa e le sue versioni, controlla una casa e salva una versione nuova. Entra con npx @blupinta/cli login, poi aggiungilo all’agente:

{ "mcpServers": { "blupinta": { "command": "npx", "args": ["-y", "@blupinta/mcp"] } } }

Python: blupinta

Ogni operazione in blupinta.v1, chiamata con Blupinta.call (o acall, con asyncio); il device flow, una casa seguita con watch_home, i webhook controllati con is_signed_webhook.

pip install blupinta

quickstart.py

"""A script's first lines with blupinta: connect with a code typed on a phone, list the projects, read a home, then
follow each new version. Compiled by the package's tests, so it can't drift from it."""

from blupinta import Blupinta, TokenKeeper, start_device_sign_in, watch_home
from blupinta.v1.api.projects import get_home, list_projects

signing_in = start_device_sign_in("openid offline_access projects:read")
print(f"Open {signing_in.verification_uri} and type {signing_in.user_code}")
tokens = signing_in.tokens()

with Blupinta(TokenKeeper(tokens, client_id="device")) as blupinta:
    project = blupinta.call(list_projects).rows[0]
    saved = blupinta.call(get_home, project.id)
    print(f"{saved.home['name']}: version {saved.number}")
    for saved, _etag in watch_home(blupinta, project.id, etag=None):
        print(f"new version {saved.number}: {saved.message}")