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.
Generates a request for the asset endpoint.
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
.
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"]
@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)
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.
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}]
@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 isfalse
.:dataset
(String.t/0
) - Sanity dataset.:http_options
(keyword/0
) - Options to be passed toFinch.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 is1
.:project_id
(String.t/0
) - Sanity project ID.:retry_delay
(pos_integer/0
) - Delay in ms to wait before retrying after an error. Applies ifmax_attempts
is greater than1
. The default value is1000
.:token
(String.t/0
) - Sanity auth token.
@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 is1000
.: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 torequest/2
. Ifmax_attempts
is omitted then it will default to3
.:variables
- Map of variables to be used withquery
. The default value is%{}
.
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
) - Optionalcontent-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
- Labeltitle
- Titledescription
- Descriptionfilename
- Original filenamemeta
- ???creditLine
- The credit to person(s) and/or organization(s) required by the supplier of the image to be used when published