python-api-sdk

name	python-api-sdk
description	Update the Python API SDK. Use this skill when the user asks to update the Python API SDK, based on the OpenAPI schema.
user-invocable	true
allowed-tools	["read_file","write_file","search_replace","grep","bash","ask_user_question","task"]

Python API SDK Skill

This skill is a complete cookbook for updating the Python API SDK. It is designed to be used when the user asks to update the Python API SDK, based on the OpenAPI schema.

Step 1: Download the OpenAPI Schema

Start by downloading a fresh OpenAPI schema from https://api.polar.sh/openapi.json. This schema will be the basis for generating the API SDK.

curl -o openapi.json https://api.polar.sh/openapi.json

Step 2: Update the generated types

We have an automatic generator that converts the OpenAPI components and query parameters into proper Python TypedDict. Before generating the API endpoints, make sure to run this generator to update the types based on the latest OpenAPI schema.

just generate-python

Step 3: Identify the Groups of Endpoints

The OpenAPI schema contains a property x-speakeasy-group that categorizes endpoints into groups. This property is used to organize the endpoints in the SDK.

Use jq to identify all the groups in the OpenAPI schema.

jq '.paths | to_entries[] | .value[].["x-speakeasy-group"]' openapi.json | sort | uniq

Step 4: Generate the API SDK Groups using the python-api-sdk-group skill

For each group identified in the previous step, generate the API SDK group. For this, load the skill python-api-sdk-group and follow the steps in the skill, and only those steps.

Repeat this process for each group identified in the OpenAPI schema.

You can use subagents to run the skill for each group in parallel. Instruct the subagents to follow closely the steps in the python-api-sdk-group skill, and only those steps.

Step 5: Format, lint and typecheck

After generating or updating the SDK, make sure to format, lint and typecheck the code to ensure that it adheres to the project's coding standards and is free of errors.

just lint

This will run the linter and type checker on the codebase. Make sure to fix any issues that are reported before considering the task complete.

Done

Once done, your task is done. No need to make follow-up testing or checks. End here and report back.