Proxy

info

The Shop Minis proxy currently only supports specific hosts. Please contact us if you would like to add a host to the list of allowed hosts.

The Shop Minis proxy allows Minis to make authenticated requests to third-party APIs without exposing their credentials in the client.

1. Set API credentials using the secrets set command:

   npx shop-minis secrets set my_api_key abc123
   caution

   Running this command will update live secrets.

2. Define a proxy configuration in manifest.json:

   {
     "proxies": [
       {
         "target_url_pattern": "https://example.com/api/*",
         "allowed_methods": ["GET"],
         "appended_headers": [
           "Authorization: Key {{ secrets.my_api_key }}",
           "Content-Type: application/json"
         ],
         "user_rate_limit_requests": 10,
         "user_rate_limit_interval": 3600
       }
     ]
   }

3. Apply the proxy configuration using the proxies apply command:

   npx shop-minis proxies apply
   caution

   Running this command will update live proxy configurations, including deleting existing ones that have been removed from manifest.json.

### Options

• target_url_pattern is a glob pattern to match against requests. Only requests with URLs matching this pattern will be forwarded.
• allowed_methods is an arrat of HTTP methods. Only requests matching these HTTP methods will be forwarded.
• appended_header is a list of headers to append to the forwarded request. These can include references to secrets for authentication. No headers will be forwarded from the client.
• user_rate_limit_requests and user_rate_limit_interval define how many requests a Shop user can make via this proxy configuration over the given period. For the example above, this is 10 requests every hour.
• body_json_schema is a JSON schema to match against requests. Only requests with JSON bodies matching this schema will be forwarded.

You can configure multiple proxy configurations and they will be matched in the order they are defined in the manifest.json file. The first matching configuration will be used.

Commands

• npx shop-minis secrets set <key> <value> will store a secret remotely for use in a proxy configuration
• npx shop-minis secrets delete <key> will delete a remotely stored secret
• npx shop-minis proxies apply will apply the local configuration in manifest.json
• npx shop-minis proxies pull will pull down the current remote configuration to manifest.json

Making a proxied request

Use the useMinisProxyFetch hook to make proxied requests inside your Mini:

import {useCallback} from 'react'
import {useMinisProxyFetch} from '@shopify/shop-minis-sdk'

const MyComponent = () => {
  const {minisProxyFetch} = useMinisProxyFetch()

  const fetchPost = useCallback(async () => {
    const post = await minisProxyFetch('https://example.com/posts/123')

    console.log(post)
  }, [minisProxyFetch])

  return <Button onPress={fetchPost} title="Fetch post" />
}

The minisProxyFetch function is API compatible with fetch.

Making a proxied request to fal.ai

The Shop Minis SDK includes a convenient wrapper for querying fal.ai using the proxy:

import {useCallback} from 'react'
import {useFalAi} from '@shopify/shop-minis-sdk'

const MyComponent = ({imageUrl}) => {
  const fal = useFalAi()

  const removeBackground = useCallback(async () => {
    const result = await fal.subscribe('fal-ai/bria/background/remove', {
      input: {image_url: imageUrl},
      mode: 'polling',
      pollInterval: 1000,
    })

    console.log(result)
  }, [fal, imageUrl])

  return <Button onPress={removeBackground} title="Remove background" />
}

info

The proxy will not support streaming responses so ensure mode is set to "polling".

It's a good idea to have separate user rate limiting configurations for initiating the request and polling for the result. Here's an example fal.ai configuration:

{
  "proxies": [
    {
      "target_url_pattern": "https://queue.fal.run/fal-ai/bria/background/remove",
      "allowed_methods": ["POST"],
      "appended_headers": ["Authorization: Key {{ secrets.fal_ai_key }}"],
      "user_rate_limit_requests": 10,
      "user_rate_limit_interval": 3600
    },
    {
      "target_url_pattern": "https://queue.fal.run/fal-ai/bria/requests*",
      "allowed_methods": ["GET"],
      "appended_headers": ["Authorization: Key {{ secrets.fal_ai_key }}"],
      "user_rate_limit_requests": 50,
      "user_rate_limit_interval": 300
    }
  ]
}

In this example, the user can make 10 background removal requests every hour, but they can poll for the results 50 times in 5 minutes.