# gRPC schema

Fetch the protobuf schema of the Synthient gRPC API.

The `@synthient/synthient/grpcschema` entry point fetches the protobuf schema of the Synthient [gRPC API](https://docs.synthient.com/grpc) using gRPC server reflection. It needs the optional peer dependencies `@grpc/grpc-js` and `@bufbuild/protobuf`, and importing it without them fails:

```bash
npm install @grpc/grpc-js @bufbuild/protobuf
```

## fetchSchema

Connects to a Synthient gRPC endpoint and uses server reflection to fetch the protobuf files that define `options.symbols`, or every listed service when there are none, along with all of their imports.

```ts
function fetchSchema(options?: FetchSchemaOptions): Promise<Schema>;
```

```ts
import { SchemaError, explain, fetchSchema } from "@synthient/synthient/grpcschema";

try {
  const schema = await fetchSchema();
  for (const file of schema.descriptorSet.file) {
    console.log(file.name, file.package);
  }
} catch (error) {
  const explanation = explain(error);
  if (error instanceof SchemaError && explanation !== "") {
    throw new Error(`${explanation} ${error.message}`, { cause: error });
  }
  throw error;
}
```

- **Errors:** Errors from the gRPC call or the reflection responses reject with a `SchemaError`, invalid options with a `TypeError` or `RangeError`, and a canceled `signal` with its reason.

## FetchSchemaOptions

With no options, `fetchSchema` fetches every service from `DEFAULT_ENDPOINT` over TLS, sending the key from `SYNTHIENT_API_KEY` if it is set.

- `apiKey?` `string | undefined` — Sent as `x-api-key` metadata when not empty. Defaults to the `SYNTHIENT_API_KEY` environment variable.
- `endpoint?` `string | undefined` — The server as `host:port`, a bare host (port 443 is assumed), or a `grpc://` or `https://` URL. Defaults to `DEFAULT_ENDPOINT`.
- `plaintext?` `boolean | undefined` — Disables TLS, for local development servers.
- `symbols?` `Iterable<string> | undefined` — Fully qualified service or message names to resolve. Empty resolves every listed service except the `grpc.reflection` services.
- `signal?` `AbortSignal | undefined` — Cancels the fetch, which rejects with the signal's reason.
- `timeout?` `number | undefined` — Milliseconds allowed for the whole fetch. Defaults to `30_000`. It must be an integer from 1 to 2147483647.

## Schema

The protobuf schema returned by `fetchSchema`.

- `endpoint` `string` — The normalized address that was queried.
- `symbols` `string[]` — The service or message names that were resolved.
- `descriptorSet` `FileDescriptorSet` — The resolved files in dependency order, each file after the files it imports. `FileDescriptorSet` comes from `@bufbuild/protobuf/wkt`.

## SchemaError

Fetching the schema failed. `explain` describes common causes. It extends `SynthientError`, and its `name` is `"SchemaError"`.

- `code` `number | undefined` — The gRPC status code, as in `status` from `@grpc/grpc-js`, or `undefined` when the failure was not a gRPC status.

```ts
constructor(message: string, code?: number, options?: ErrorOptions);
```

## explain

Returns a human-readable explanation of a common `fetchSchema` error, or `""` if it has none, including for any error that is not a `SchemaError`.

```ts
function explain(error: unknown): string;
```

| gRPC status         | Explanation                                                                                              |
| ------------------- | -------------------------------------------------------------------------------------------------------- |
| `UNAUTHENTICATED`   | Missing or invalid API key.                                                                              |
| `PERMISSION_DENIED` | This API key does not have permission to inspect gRPC schemas.                                           |
| `NOT_FOUND`         | No protobuf schema found for the requested symbol. Fetch without symbols to list the available services. |
| `UNIMPLEMENTED`     | The gRPC endpoint does not expose server reflection.                                                     |
| `UNAVAILABLE`       | Could not reach the gRPC endpoint. Check the address, network access, and TLS settings.                  |
| `DEADLINE_EXCEEDED` | Timed out reading protobuf schemas from gRPC reflection. Use a longer timeout.                           |

## normalizeEndpoint

Converts `raw` to `host:port` form and returns it with the host name used for TLS.

```ts
function normalizeEndpoint(raw: string): {
  endpoint: string;
  host: string;
};
```

- **Input:** It accepts `host:port`, a bare host (port 443 is assumed), and `grpc://` or `https://` URLs. An empty `raw` uses `DEFAULT_ENDPOINT`.

The address of the Synthient gRPC API.

```ts
const DEFAULT_ENDPOINT = "grpc.synthient.com:443";
```