Skip to content

Add branding format support to JS and Python SDKs - #2360

Merged
nickscamara merged 3 commits into
mainfrom
devin/1762285156-add-branding-format-to-sdks
Nov 5, 2025
Merged

nickscamara merged 3 commits into
mainfrom
devin/1762285156-add-branding-format-to-sdks

Conversation

@devin-ai-integration

@devin-ai-integration devin-ai-integration Bot commented Nov 4, 2025

Copy link
Copy Markdown
Contributor

Add branding format support to JS and Python SDKs

Summary

This PR adds type definitions for the branding format to both the JavaScript/TypeScript and Python SDKs. The branding format is already implemented and supported in the API but was missing from the SDK type definitions.

Changes:

  • Added 'branding' to the FormatString type union in both SDKs
  • Created BrandingProfile interface/class with comprehensive type definitions including:
    • Color schemes (light/dark), colors, fonts, typography
    • Spacing, components (buttons, inputs), icons, images
    • Layout, animations, tone, personality
  • Added branding?: BrandingProfile field to the Document type in both SDKs

The types were copied from the API's existing apps/api/src/types/branding.ts to ensure compatibility.

Review & Testing Checklist for Human

  • End-to-end test with JS SDK: Test scraping with formats: ["branding"] and verify the returned branding data is properly typed and matches the BrandingProfile interface
  • End-to-end test with Python SDK: Test scraping with formats: ["branding"] and verify the returned branding data is properly typed and matches the BrandingProfile class
  • Verify type completeness: Check that the BrandingProfile types match what the API actually returns in production (the API tests for branding are currently skipped, which may indicate special setup requirements or instability)

Test Plan

// JS SDK test
const client = new Firecrawl({ apiKey: 'fc-...' });
const result = await client.scrape('https://firecrawl.dev', { 
  formats: ['branding'] 
});
console.log(result.branding); // Should be typed as BrandingProfile
# Python SDK test
from firecrawl import Firecrawl
client = Firecrawl(api_key='fc-...')
result = client.scrape('https://firecrawl.dev', formats=['branding'])
print(result.branding)  # Should be typed as BrandingProfile

Notes

  • The JS SDK build passes successfully with no new errors
  • The Python SDK uses more generic Dict[str, Any] types for nested structures compared to TypeScript's more specific types, which is acceptable for Python's dynamic nature
  • The API implementation already exists in apps/api/src/lib/branding/ with comprehensive branding extraction logic

Link to Devin run: https://app.devin.ai/sessions/24af7e0ad2d64415966c1abf54522ada
Requested by: abi@sideguide.dev (@abimaelmartell)


Summary by cubic

Adds branding format support to the JS and Python SDKs, aligned with the API’s existing branding schema. Request ["branding"] to get typed data via Document.branding; Python normalizes colorScheme to color_scheme.

  • New Features

    • Added "branding" to FormatString in both SDKs.
    • Introduced BrandingProfile type/class (colors, fonts, typography, spacing, components, icons, images, animations, layout, tone, personality).
    • Added Document.branding in both SDKs.
  • Bug Fixes

    • Python: normalize branding.colorScheme -> color_scheme for consistent snake_case.

Written for commit 558a1eb. Summary will update automatically on new commits.

Co-Authored-By: abi@sideguide.dev <abimex@gmail.com>
@devin-ai-integration

Copy link
Copy Markdown
Contributor Author

🤖 Devin AI Engineer

I'll be helping with this pull request! Here's what you should know:

✅ I will automatically:

  • Address comments on this PR. Add '(aside)' to your comment to have me ignore it.
  • Look at CI failures and help fix them

Note: I can only respond to comments from users who have write access to this repository.

⚙️ Control Options:

  • Disable automatic comment and CI monitoring

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 2 files

- Add JS SDK unit tests in branding.test.ts with 4 test cases
- Add Python SDK unit tests in test_branding.py with 5 test cases
- Update Python SDK normalize_document_input to handle colorScheme -> color_scheme conversion
- Add model_config extra='allow' to BrandingProfile for future extensibility
- All tests pass locally (25 JS tests, 5 Python tests)

Co-Authored-By: abi@sideguide.dev <abimex@gmail.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 4 files

- Bump JS SDK version from 4.4.1 to 4.5.0
- Bump Python SDK version from 4.5.0 to 4.6.0

Version bumps reflect the addition of branding format support and comprehensive unit tests.

Co-Authored-By: abi@sideguide.dev <abimex@gmail.com>

@cubic-dev-ai cubic-dev-ai Bot left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

No issues found across 2 files

@nickscamara
nickscamara merged commit dabf991 into main Nov 5, 2025
9 of 10 checks passed
jerbao pushed a commit to jerbao/firecrawl-custom that referenced this pull request Aug 22, 2026
* Add branding format support to JS and Python SDKs

Co-Authored-By: abi@sideguide.dev <abimex@gmail.com>

* Add comprehensive unit tests for branding format in both SDKs

- Add JS SDK unit tests in branding.test.ts with 4 test cases
- Add Python SDK unit tests in test_branding.py with 5 test cases
- Update Python SDK normalize_document_input to handle colorScheme -> color_scheme conversion
- Add model_config extra='allow' to BrandingProfile for future extensibility
- All tests pass locally (25 JS tests, 5 Python tests)

Co-Authored-By: abi@sideguide.dev <abimex@gmail.com>

* Bump SDK versions for branding format release

- Bump JS SDK version from 4.4.1 to 4.5.0
- Bump Python SDK version from 4.5.0 to 4.6.0

Version bumps reflect the addition of branding format support and comprehensive unit tests.

Co-Authored-By: abi@sideguide.dev <abimex@gmail.com>

---------

Co-authored-by: Devin AI <158243242+devin-ai-integration[bot]@users.noreply.github.com>
Co-authored-by: abi@sideguide.dev <abimex@gmail.com>
zeekay pushed a commit to Dream-AI-4444/firecrawl that referenced this pull request Sep 10, 2026
* Add branding format support to JS and Python SDKs

Co-Authored-By: abi@sideguide.dev <abimex@gmail.com>

* Add comprehensive unit tests for branding format in both SDKs

- Add JS SDK unit tests in branding.test.ts with 4 test cases
- Add Python SDK unit tests in test_branding.py with 5 test cases
- Update Python SDK normalize_document_input to handle colorScheme -> color_scheme conversion
- Add model_config extra='allow' to BrandingProfile for future extensibility
- All tests pass locally (25 JS tests, 5 Python tests)

Co-Authored-By: abi@sideguide.dev <abimex@gmail.com>

* Bump SDK versions for branding format release

- Bump JS SDK version from 4.4.1 to 4.5.0
- Bump Python SDK version from 4.5.0 to 4.6.0

Version bumps reflect the addition of branding format support and comprehensive unit tests.

Co-Authored-By: abi@sideguide.dev <abimex@gmail.com>

---------

Co-authored-by: abi@sideguide.dev <abimex@gmail.com>

Co-authored-by: Hanzo Dev <dev@hanzo.ai>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant