View Source Sanity (sanity v2.0.0)

Client library for Sanity CMS. See the README for examples.

Summary

Functions

Generates a request for the Doc endpoint.

Returns a list of document IDs referenced by a document or list of documents.

Generates a request for the Mutate endpoint.

Generates a request to the Query endpoint. Requests to this endpoint may be authenticated or unauthenticated. Unauthenticated requests to a dataset with private visibility will succeed but will not return any documents.

Replaces Sanity references. The input can be a single document or list of documents. References can be deeply nested within the documents. Documents can have either atom or string keys.

Submits a request to the Sanity API. Returns {:ok, response} upon success or {:error, response} if a non-exceptional (4xx) error occurs. A Sanity.Error will be raised if an exceptional error such as a 5xx response code, a network timeout, or a response containing non-JSON content occurs.

Like request/2, but raises a Sanity.Error instead of returning and error tuple.

Returns the result from a Sanity.Response struct.

Returns a lazy Stream of results for the given query. The implementation is efficient and suitable for iterating over very large datasets. It is based on the Paginating with GROQ article from the Sanity docs.

Generates a request for the asset endpoint. The body argument can be a binary or iolist to upload content from memory. Or it can be an Enumerable, such as a value returned by File.stream!/2, for streaming uploads.

Functions

@spec doc(String.t()) :: Sanity.Request.t()

Generates a request for the Doc endpoint.

The Sanity docs suggest using this endpoint sparingly because it is "less scalable/performant" than using query/3.

Link to this function

list_references(doc_or_docs)

View Source

Returns a list of document IDs referenced by a document or list of documents.

Examples

iex> Sanity.list_references(%{_ref: "abc", _type: "reference"})
["abc"]

iex> Sanity.list_references([%{"_ref" => "one", "_type" => "reference"}, %{_ref: "two"}, %{"items" => [%{"_ref" => "three"}]}])
["one", "two", "three"]

iex> Sanity.list_references([%{_ref: "abc", _type: "reference"}])
["abc"]

iex> Sanity.list_references([%{a: %{_ref: "abc", _type: "reference"}, b: 1}])
["abc"]
Link to this function

mutate(mutations, query_params \\ [])

View Source
@spec mutate([map()], keyword() | map()) :: Sanity.Request.t()

Generates a request for the Mutate endpoint.

Examples

Sanity.mutate(
  [
    %{
      create: %{
        _type: "product",
        title: "Test product"
      }
    }
  ],
  return_ids: true
)
|> Sanity.request(config)
Link to this function

query(query, variables \\ %{}, query_params \\ [])

View Source
@spec query(String.t(), keyword() | map(), keyword() | map()) :: Sanity.Request.t()

Generates a request to the Query endpoint. Requests to this endpoint may be authenticated or unauthenticated. Unauthenticated requests to a dataset with private visibility will succeed but will not return any documents.

Perspectives can be used by passing the "perspective" query param like, Sanity.query("*", %{}, perspective: "previewDrafts"). This function does not set a perspective by default, which is equivalent to a perspective of "raw".

Link to this function

replace_references(doc_or_docs, func)

View Source
@spec replace_references(list() | map(), (... -> any())) :: list() | map()

Replaces Sanity references. The input can be a single document or list of documents. References can be deeply nested within the documents. Documents can have either atom or string keys.

Examples

iex> Sanity.replace_references(%{_ref: "abc", _type: "reference"}, fn "abc" -> %{_id: "abc"} end)
%{_id: "abc"}

iex> Sanity.replace_references(%{"_ref" => "abc", "_type" => "reference"}, fn "abc" -> %{"_id" => "abc"} end)
%{"_id" => "abc"}

iex> Sanity.replace_references(%{_ref: "abc"}, fn "abc" -> %{_id: "abc"} end)
%{_id: "abc"}

iex> Sanity.replace_references(%{"_ref" => "abc"}, fn "abc" -> %{"_id" => "abc"} end)
%{"_id" => "abc"}

iex> Sanity.replace_references([%{_ref: "abc", _type: "reference"}], fn _ -> %{_id: "abc"} end)
[%{_id: "abc"}]

iex> Sanity.replace_references([%{a: %{_ref: "abc", _type: "reference"}, b: 1}], fn _ -> %{_id: "abc"} end)
[%{a: %{_id: "abc"}, b: 1}]
Link to this function

request(request, opts \\ [])

View Source
@spec request(
  Sanity.Request.t(),
  keyword()
) :: {:ok, Sanity.Response.t()} | {:error, Sanity.Response.t()}

Submits a request to the Sanity API. Returns {:ok, response} upon success or {:error, response} if a non-exceptional (4xx) error occurs. A Sanity.Error will be raised if an exceptional error such as a 5xx response code, a network timeout, or a response containing non-JSON content occurs.

Options

  • :api_version (String.t/0) - The default value is "v2021-10-21".

  • :cdn (boolean/0) - Should the CDN be used? See the Sanity docs for details. The default value is false.

  • :dataset (String.t/0) - Required. Sanity dataset.

  • :http_options (keyword/0) - Options to be passed to Req.request/1. The default value is [receive_timeout: 30000].

  • :project_id (String.t/0) - Required. Sanity project ID.

  • :token (String.t/0) - Sanity auth token.

Link to this function

request!(request, opts \\ [])

View Source
@spec request!(
  Sanity.Request.t(),
  keyword()
) :: Sanity.Response.t()

Like request/2, but raises a Sanity.Error instead of returning and error tuple.

See request/2 for supported options.

@spec result!(Sanity.Response.t()) :: any()

Returns the result from a Sanity.Response struct.

Examples

iex> Sanity.result!(%Sanity.Response{body: %{"result" => []}})
[]

iex> Sanity.result!(%Sanity.Response{body: %{}, status: 200})
** (Sanity.Error) %Sanity.Response{body: %{}, headers: %{}, status: 200}
@spec stream(Keyword.t()) :: Enumerable.t()

Returns a lazy Stream of results for the given query. The implementation is efficient and suitable for iterating over very large datasets. It is based on the Paginating with GROQ article from the Sanity docs.

Failed attempts to fetch a batch will be retried by default. If the max attempts are exceeded then an exception will be raised as descrbied in request!/2.

The current implementation always sorts by ascending _id. Support for sorting by other fields may be supported in the future.

Options

  • :batch_size (pos_integer/0) - Number of results to fetch per request. The Sanity docs say: "In the general case, we recommend a batch size of no more than 5,000. If your documents are very large, a smaller batch size is better." The default value is 1000.

  • :perspective (String.t/0) - Perspective to use. Common values are "published", "previewDrafts", and "raw". See the docs for details. The default value is "published".

  • :projection (String.t/0) - GROQ projection. Must include the _id field. The default value is "{ ... }".

  • :query (String.t/0) - Query string, like _type == "page". By default, all documents will be selected.

  • :request_opts (keyword/0) - Required. Options to be passed to request/2.

  • :variables - Map of variables to be used with query. The default value is %{}.

Link to this function

upload_asset(body, opts \\ [], query_params \\ [])

View Source
@spec upload_asset(iodata() | Enumerable.t(), keyword() | map(), keyword() | map()) ::
  Sanity.Request.t()

Generates a request for the asset endpoint. The body argument can be a binary or iolist to upload content from memory. Or it can be an Enumerable, such as a value returned by File.stream!/2, for streaming uploads.

Options

  • :asset_type - Either :image or :file. The default value is :image.

  • :content_type (String.t/0) - Optional content-type header. It appears that Sanity is able to infer image types.

Query params

Sanity doesn't document the query params very well at this time, but the Sanity Javascript client lists several possible query params:

  • label - Label
  • title - Title
  • description - Description
  • filename - Original filename
  • meta - ???
  • creditLine - The credit to person(s) and/or organization(s) required by the supplier of the image to be used when published