> ## Documentation Index
> Fetch the complete documentation index at: https://docs.userkit.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Filas de recurso

> Acesso antecipado, um recurso por vez: quem já tem conta pede uma parte do produto, e uma flag deixa entrar.

Uma fila de recurso é um **pedido**, nunca uma porta: quem está nela já tem
conta, já está logado pelo seu próprio auth, e o que está esperando é uma parte
do produto — o checkout novo, o editor novo, a API que ainda está em beta.

Por isso ela nunca toca em autenticação. Estar em dez filas de recurso não muda
nada no login de ninguém, e pedir um recurso não é entrar — então nada aqui cria
sessão, manda um caminho de entrada nem recusa um.

### Pedindo

A chave da fila é a chave da **flag** do recurso, no mesmo ambiente. Uma fila
sem flag por trás responde `404 unknown_waitlist` — e isso é de propósito: quem
libera o recurso é a flag (veja [Ligando a feature de
verdade](#ligando-a-feature-de-verdade)), então uma fila sem flag seria uma
lista sobre a qual ninguém consegue agir. Também é o que impede que a chave
vire texto livre escrito por quem tiver uma sessão de contato.

Crie a flag desligada antes de abrir os pedidos: é exatamente para isso que ela
já nasce em `false`.

```ts theme={null}
const request = await userkit.joinFeatureWaitlist("beta-checkout", {
  metadata: { using: "uma API para compiladores" },
});
// { waitlist: "beta-checkout", status: "waiting", position: 12, … }
```

No React, o hook desenha o botão inteiro:

```tsx theme={null}
import { useFeatureWaitlist } from "@userkit/react";

function BetaCheckoutButton() {
  const beta = useFeatureWaitlist("beta-checkout");
  if (beta.loading) return null;
  if (beta.status === "admitted") return <p>Você já tem acesso.</p>;
  if (beta.status === "waiting") return <p>Você é o {beta.position}º da fila.</p>;
  return <button onClick={() => void beta.request()}>Quero testar</button>;
}
```

Pedir duas vezes mantém o primeiro lugar e responde a mesma coisa, então o botão
nunca precisa distinguir "acabou de entrar" de "já estava". Nada é enviado por
e-mail: a pessoa está dentro do seu produto olhando para a resposta.

`cancel()` desfaz o pedido — e é recusado com `409 already_admitted` depois de
liberado, porque tirar acesso é um ato seu, no painel, e não desta rota.

A fila aparece no painel a partir do primeiro pedido, em **Lista de espera**,
no seletor de fila — o painel lista as filas que têm gente, não as flags que
existem.

### Liberando

```bash theme={null}
curl -s "$API/v1/organization/waitlist/admit?environment=live&waitlist=beta-checkout" \
  -H "Authorization: Bearer uk_st_…" \
  -H 'Content-Type: application/json' \
  -d '{ "all": true, "label": "o novo checkout" }'
```

Aqui liberar não anexa senha nem manda link: essas pessoas já têm conta. O que
ele faz é registrar que elas entraram — e publicar um fato por pessoa, que é o
que a audiência lê. O `label` é o nome do recurso no aviso por e-mail; sem ele o
aviso cai na chave da fila. `"notify": false` desliga o aviso, para quando o seu
produto anuncia o acesso por conta própria.

### Ligando a feature de verdade

Liberar não acende nada sozinho — quem acende é a sua flag, apontada para um
segmento de quem foi liberado:

<Steps>
  <Step title="Um segmento">
    Em **Segmentos**, uma condição: *foi liberado em* `beta-checkout`.
  </Step>

  <Step title="Uma flag apontando para ele">
    Em **Feature flags**, a flag `beta-checkout` com esse segmento como público.
  </Step>

  <Step title="O seu código lê a flag">
    `useFlag("beta-checkout")` — como qualquer outra. Cada pessoa liberada entra
    na audiência em segundos, porque a liberação publica um fato por pessoa.
  </Step>
</Steps>

É de propósito que a fila não acenda a feature diretamente: quem decide o que
cada pessoa vê é a flag, e uma fila que ligasse recursos sozinha seria um
segundo lugar para responder a mesma pergunta — que é exatamente o que os
segmentos existem para evitar.

<Note>
  Quem nunca pediu não está *esperando*. As duas condições do segmento —
  *foi liberado em* e *está esperando em* — são positivas, e quem não tem pedido
  nenhum não entra em nenhuma das duas. "Todo mundo menos os liberados" já é o que
  a flag é quando está desligada.
</Note>