sanity_client

SanityClient runs GROQ queries using an injected or default HTTP client. SanityConfig selects project, dataset, API version, perspective, and CDN behavior. The client also builds image/file URLs and provides a live query stream.

How the pieces fit together

Package source · Released API

Choose a declaration

BadRequestException · FetchDataException · ImageOptions · InvalidReferenceException · LiveConfig · LiveConnect · LiveConnectException · PerformanceInfo · Perspective · SanityClient · SanityConfig · SanityDataset · SanityException · SanityQueryResponse · SanityRequest · SanityUrlBuilder · ServerResponse · UnauthorizedException · UrlBuilder

BadRequestException

Source

Exception when the request is invalid.

final class BadRequestException extends SanityException

Directly declared public members:

BadRequestException([final String? message]);

Creates a new bad request exception.

FetchDataException

Source

Exception thrown when a document is not found.

final class FetchDataException extends SanityException

Directly declared public members:

FetchDataException([final String? message]);

Creates a new fetch data exception.

ImageOptions

Source

Options to customize the image URL.

class ImageOptions

Directly declared public members:

final int? width;

The width of the image in pixels.

final int? height;

The height of the image in pixels.

final int? devicePixelRatio;

The device pixel ratio of the image.

final int? quality;

The quality of the image, expressed as value between 0-100

final String? format;

The format of the image. Can be either jpg, png, webp, or auto.

ImageOptions({this.width, this.height, this.devicePixelRatio, this.quality, this.format});

Creates a new image options object with the provided parameters. This handles width, height, device pixel ratio, quality, and format.

InvalidReferenceException

Source

Exception when the request is forbidden.

final class InvalidReferenceException extends SanityException

Directly declared public members:

InvalidReferenceException([final String? message]);

Creates a new invalid reference exception.

LiveConfig

Source

Configuration for live queries

class LiveConfig

Directly declared public members:

final bool includeDrafts;

Whether to include drafts in the query

LiveConfig({this.includeDrafts = false});

Creates a new LiveConfig object with the provided includeDrafts parameter.

LiveConfig.withDrafts();

Creates a new LiveConfig object with the includeDrafts parameter set to true.

LiveConnect

Source

Public declaration in this package.

extension LiveConnect on SanityClient

Directly declared public members:

Stream<SanityQueryResponse> fetchLive(String query, {Map<String, String>? params, includeDrafts = false});

Fetches data from Sanity using Server-Sent Events (SSE) for live updates.

LiveConnectException

Source

Exception when connecting to the live subscription.

final class LiveConnectException extends SanityException

Directly declared public members:

LiveConnectException([final String? message]);

Creates a new live connect exception.

PerformanceInfo

Source

A class that extracts various performance information from a Sanity response.

final class PerformanceInfo

Directly declared public members:

final String query;

The query that was sent to the server.

final int serverTimeMs;

The time it took for the server to respond to the query.

final int clientTimeMs;

The time it took for the client to process the response. This is the complete round-trip time.

final String shard;

The shard that the query was sent to.

final int age;

The age of the data that was returned in the response.

PerformanceInfo({required this.query, required this.serverTimeMs, required this.clientTimeMs, required this.shard, required this.age});

Creates a new performance information object with the given query, server timing, client timing, shard and age.

Perspective

Source

The various perspectives that can be used to fetch data from Sanity

enum Perspective

SanityClient

Source

The client for fetching data from Sanity

final class SanityClient

Directly declared public members:

final SanityConfig config;

The configuration for the client

http.Client httpClient;

The HTTP client to use. Generally not needed to be provided. It can be set during testing or when used in the context of a framework that has its own http.Client instance.

final UrlBuilder urlBuilder;

The URL builder to use. When not provided it uses the default Sanity URL builder

SanityClient(this.config, {final http.Client? httpClient, final UrlBuilder? urlBuilder});

Creates a new Sanity client with the provided configuration. Use the optional parameters to provide a custom HTTP client or URL builder.

void setHttpClient(http.Client client);

Set the HTTP client to use for fetching data

Future<SanityQueryResponse> fetch(String query, {Map<String, String>? params});

Fetches data from Sanity by running the GROQ Query with the passed in parameters

Uri imageUrl(final String imageRefId, {final int? width, final int? height, final int? devicePixelRatio, final int? quality, final String? format});

Return the associated image url

Uri fileUrl(final String fileRefId);

Return the associated object url

Future<List<SanityDataset>> datasets();

Fetches the associated datasets with this project

SanityConfig

Source

Configuration for the Sanity client

final class SanityConfig

Directly declared public members:

final String dataset;

The dataset to fetch data from

final String projectId;

The project id

final String? token;

The token to use for authentication

final bool useCdn;

Whether to use the CDN or not

final String apiVersion;

The API version to use. It follows the format vYYYY-MM-DD

final Perspective perspective;

The perspective to use

final bool explainQuery;

Whether to explain the query or not

static final String defaultApiVersion;

The default API version to use

static EventFlux Function() createEventFlux;

SanityConfig({required this.projectId, required this.dataset, this.token, String? apiVersion, bool? useCdn, Perspective? perspective, bool? explainQuery});

Creates a new Sanity configuration for fetching documents from a project and dataset

SanityDataset

Source

A class to represent a Sanity dataset.

class SanityDataset

Directly declared public members:

final String name;

The name of the dataset.

final String aclMode;

The ACL mode of the dataset.

SanityDataset({required this.name, required this.aclMode});

Creates a new Sanity dataset with the given name and ACL mode.

factory SanityDataset.fromJson(final Map<String, dynamic> json);

Creates a new Sanity dataset from a JSON map.

bool ==(final Object other);

int get hashCode;

SanityException

Source

Base type for exceptions thrown by the Sanity client.

abstract base class SanityException implements Exception

Directly declared public members:

SanityException([this._message, this._prefix]);

Creates a new Sanity exception.

String toString();

SanityQueryResponse

Source

A class that represents a Sanity query response.

final class SanityQueryResponse

Directly declared public members:

final dynamic result;

The result of the query, which can be a null, object or array.

final List<String> syncTags;

Sync Tags of the query, which will be used in case of a Live Fetch Query

final PerformanceInfo info;

The performance information of the query.

SanityQueryResponse({required this.result, required this.info, this.syncTags = const []});

Creates a new Sanity query response with the given result and performance information.

SanityRequest

Source

Public declaration in this package.

class SanityRequest

Directly declared public members:

final UrlBuilder urlBuilder;

final String query;

final Map<String, String>? params;

final LiveConfig? live;

SanityRequest({required this.urlBuilder, required this.query, this.params, this.live});

bool get requiresPost;

Queries longer than 11kB can’t be submitted using the GET method, so they must be POSTed. See https://www.sanity.io/docs/http-query

Uri get getUri;

Uri get postUri;

Map<String, dynamic> toPostBody();

Strips the $-prefixes when submitting as json params via POST

SanityUrlBuilder

Source

A URL builder implementation for Sanity.

final class SanityUrlBuilder extends UrlBuilder<SanityConfig>

Directly declared public members:

SanityUrlBuilder(super.config);

Creates a new Sanity URL builder with the provided configuration.

Uri fileUrl(String fileRefId);

static String fileName(String fileRefId);

Generates the file name from the file reference ID.

Uri imageUrl(String imageRefId, {ImageOptions? options});

static String imageFileName(String imageRefId);

Generates the image file name from the image reference ID.

Uri queryUrl(String query, {Map<String, dynamic>? params, LiveConfig? live});

ServerResponse

Source

A class to represent a Sanity response to a query.

class ServerResponse

Directly declared public members:

final dynamic result;

The result of the query, which can be a null, object or array.

final int ms;

The time it took for the server to respond to the query.

final String query;

The query that was sent to the server.

final List<String> syncTags;

ServerResponse({required this.result, required this.ms, required this.query, this.syncTags = const []});

Creates a new server response with the given result, time and query.

factory ServerResponse.fromJson(Map<String, dynamic> json);

Creates a new server response from a JSON map.

UnauthorizedException

Source

Exception when the request is unauthorized and does not include a valid token in the Authorization header.

final class UnauthorizedException extends SanityException

Directly declared public members:

UnauthorizedException([final String? message]);

Creates a new unauthorized exception.

UrlBuilder

Source

Provides the main interface for building URLs for Sanity assets.

abstract class UrlBuilder<TConfig>

Directly declared public members:

final TConfig config;

The configuration object for the client, which is specific to the URL builder implementation.

UrlBuilder(this.config);

Creates a new URL builder with the provided configuration.

Uri fileUrl(String fileRefId);

Builds a URL for a file asset.

Uri imageUrl(String imageRefId, {ImageOptions? options});

Builds a URL for an image asset.

Uri queryUrl(String query, {Map<String, String>? params, LiveConfig? live});

Builds a URL for a GROQ query.