feat: expose purgeCache

[mansueli]

What kind of change does this PR introduce?

The goal is to expose the purgeCache operation from the API to the client libraries.

        "/cdn/{bucketName}/{wildcard}": {
            "delete": {
                "summary": "Purge cache for an object",
                "tags": [
                    "object"
                ],
                "parameters": [
                    {
                        "schema": {
                            "type": "string"
                        },
                        "example": "avatars",
                        "in": "path",
                        "name": "bucketName",
                        "required": true
                    },
                    {
                        "schema": {
                            "type": "string"
                        },
                        "example": "folder/cat.png",
                        "in": "path",
                        "name": "*",
                        "required": true
                    },
                    {
                        "schema": {
                            "type": "string"
                        },
                        "example": "Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJpc3MiOiJzdXBhYmFzZS1kZW1vIiwicm9sZSI6ImFub24ifQ.625_WdcF3KHqz5amU0x2X5WWHP-OEs_4qj0ssLNHzTs",
                        "in": "header",
                        "name": "authorization",
                        "required": true
                    }
                ],
                "responses": {
                    "200": {
                        "description": "Successful response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "description": "Successful response",
                                    "type": "object",
                                    "properties": {
                                        "message": {
                                            "type": "string",
                                            "examples": [
                                                "success"
                                            ]
                                        }
                                    }
                                }
                            }
                        }
                    },
                    "4XX": {
                        "description": "Error response",
                        "content": {
                            "application/json": {
                                "schema": {
                                    "description": "Error response",
                                    "$ref": "#/components/schemas/def-1"
                                }
                            }
                        }
                    }
                }
            }
        },

What is the current behavior?

There's no support this in the client libraries.

What is the new behavior?

The goal is to allow this to be exposed in the supabase-js client e.g:

storage.from(BUCKET_ID).purgeCache('test.png')

Additional context

Add any other context or screenshots.

[itslenny]

This looks great overall. I ran tests against production purging individual objects and folders with 100s of objects and both are working well.

The folder detection is wrong (see other comment) so I get "object not found" for each folder currently, but after that's fixed this should work as expected

[github-actions]

🚀 Preview Release Status

false

---

_{Last updated: 2025-08-29T15:38:40Z}

[mandarini]

Looks good to me. @itslenny what do you think? I think your comments were addressed!

[mandarini]

Moved here: supabase/supabase-js#1742 @itslenny please can you take a last look at that PR?