View Source Sanity (sanity v1.2.0)

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

Link to this section 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.

Link to this section 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

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

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.

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

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

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) - Sanity dataset.

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

  • :max_attempts (pos_integer/0) - Number of attempts to make before returning error. Requests receiving an HTTP status code of 4xx will not be retried. The default value is 1.

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

  • :retry_delay (pos_integer/0) - Delay in ms to wait before retrying after an error. Applies if max_attempts is greater than 1. The default value is 1000.

  • :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

Examples

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

iex> Sanity.result!(%Sanity.Response{body: %{}, status: 200})
** (Sanity.Error) %Sanity.Response{body: %{}, headers: nil, 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

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.

  • :drafts - Use :exclude to exclude drafts, :include to include drafts along with published docs, or :only to fetch drafts and not published documents. The default value is :exclude.

  • :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. If max_attempts is omitted then it will default to 3.

  • :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(), keyword() | map(), keyword() | map()) ::
  Sanity.Request.t()

Generates a request for the asset endpoint.

options

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

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