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
.
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"]
@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)
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"
.
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}]
@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 isfalse
.:dataset
(String.t/0
) - Required. Sanity dataset.:http_options
(keyword/0
) - Options to be passed toReq.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.
@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 is1000
.: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 torequest/2
.:variables
- Map of variables to be used withquery
. The default value is%{}
.
@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
) - Optionalcontent-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
- 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