{"id":25015209,"url":"https://github.com/cowprotocol/app-data","last_synced_at":"2025-04-12T23:13:52.220Z","repository":{"id":47985064,"uuid":"506632600","full_name":"cowprotocol/app-data","owner":"cowprotocol","description":"AppData Schema definitions","archived":false,"fork":false,"pushed_at":"2025-01-02T19:14:02.000Z","size":565,"stargazers_count":4,"open_issues_count":13,"forks_count":7,"subscribers_count":6,"default_branch":"main","last_synced_at":"2025-04-12T23:13:46.045Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cowprotocol.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2022-06-23T12:32:31.000Z","updated_at":"2025-01-03T20:53:27.000Z","dependencies_parsed_at":"2024-03-18T12:47:02.833Z","dependency_job_id":"50c144aa-b8a2-4c1f-9b3b-8be292c40d9b","html_url":"https://github.com/cowprotocol/app-data","commit_stats":{"total_commits":30,"total_committers":7,"mean_commits":4.285714285714286,"dds":0.4666666666666667,"last_synced_commit":"e93224a97ab19a2506fdabf74760788ae9a48e57"},"previous_names":[],"tags_count":46,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowprotocol%2Fapp-data","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowprotocol%2Fapp-data/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowprotocol%2Fapp-data/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cowprotocol%2Fapp-data/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cowprotocol","download_url":"https://codeload.github.com/cowprotocol/app-data/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248643006,"owners_count":21138355,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-05T08:18:20.899Z","updated_at":"2025-04-12T23:13:52.201Z","avatar_url":"https://github.com/cowprotocol.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# @cowprotocol/app-data\n\nAppData schema definitions\n\nThese schemas are used in the data encoded on `appData` field for CowProtocol orders.\n\nFor more details, check [the docs](https://docs.cow.fi/cow-sdk/order-meta-data-appdata).\n\n## Installation\n\n```bash\nyarn add @cowprotocol/app-data\n```\n\n## Usage\n\n```typescript\nimport { MetadataApi } from '@cowprotocol/app-data'\n\nexport const metadataApi = new MetadataApi()\n\nconst appCode = 'YOUR_APP_CODE'\nconst environment = 'prod'\nconst referrer = { address: `REFERRER_ADDRESS` }\n\nconst quote = { slippageBips: 1 } // Slippage percent, it's 0 to 100\nconst orderClass = { orderClass: 'market' } // \"market\" | \"limit\" | \"liquidity\"\n\nconst appDataDoc = await metadataApi.generateAppDataDoc({\n  appCode,\n  environment,\n  metadata: {\n    referrer,\n    quote,\n    orderClass,\n  },\n})\n```\n\n### Schemas\n\nSchemas are exposed as json files, where the version is the file name:\n\n```js\n// Getting the version v0.4.0\nconst schema = require('@cowprotocol/app-data/schemas/v0.4.0.json')\n\n// Now you can for example run validation against a schema\n```\n\n### Type definitions\n\nThere are also type definitions\n\n```js\nimport { v0_4_0 } from '@cowprotocol/app-data'\n\n// Note: this example is\nfunction createAppDataV0_4_0(appCode: v0_4_0.AppCode, metadata: v0_4_0.Metadata): v0_4_0.AppDataRootSchema {\n  return {\n    version: '0.4.0',\n    appCode,\n    metadata,\n  }\n}\n```\n\n### Constants\n\nThe latest version names are exposed as constants\n\n```js\nimport {\n  LATEST_APP_DATA_VERSION,\n  LATEST_QUOTE_METADATA_VERSION,\n  LATEST_REFERRER_METADATA_VERSION,\n} from '@cowprotocol/app-data'\n```\n\n### Utils\n\n_Get appData schema_\n\nTo get a schema definition by version\n\n```js\nimport { getAppDataSchema } from '@cowprotocol/app-data'\n\nconst schema = getAppDataSchema('0.1.0')\n```\n\nIt'll throw if the version does not exist\n\n_Validate appDataDoc_\n\nTo validate a document, pass it to `validateAppDataDoc`.\nIt'll return an object with a boolean indicating `success` and `errors`, if any.\nThe version to validate against will be taken from the doc itself.\n\n```js\nimport { validateAppDataDoc } from '@cowprotocol/app-data'\n\nlet doc = { version: '0.4.0', metadata: {} }\n\nlet result = await validateAppDataDoc(doc)\nconsole.log(result) // { success: true }\n\ndoc = { version: '0.0.0', metadata: {} }\n\nresult = await validateAppDataDoc(doc)\n// Contrary to `getAppDataSchema`, invalid or non-existing schemas won't throw\nconsole.log(result) // { success: false, errors: 'AppData version 0.0.0 doesn\\'t exist'}\n```\n\n# Contribute\n\nFork the repo so you can create a new PR. Then:\n\n1. Add a new version for the schema using the [semver](https://semver.org/) convention\n\n- Just duplicate the latest version i.e. `src/schemas/\u003cold-version\u003e.json` to `src/schemas/\u003cnew-version\u003e.json`\n\n2. If you are adding a new meta-data\n\n- We create one directory per schema, so we can keep track of all versions. Create the directory and initial schema definition: `\u003cmeta-data-name\u003e/v0.1.0.json`\n- Add it to the main schema you just created in step 1: `\"$ref\": \"\u003cmeta-data-name\u003e/v0.1.0.json#\"`.\n- Example: \u003chttps://github.com/cowprotocol/app-data/pull/44/files#diff-7f7a61b478245dfda004f64bd68ac55ef68cbeb5d6d90d77e1cdbd2b7e1212b8R56\u003e\n\n3. If you are modifying an existing meta-data\n\n- Version it using the [semver](https://semver.org/) convention\n- You will need to create the new file for the meta-data schema: `\u003cmeta-data-name\u003e/\u003cnew-version\u003e.json`\n- Update it in the main schema you just created in step 1: Set it to `\"\u003cmeta-data-name\u003e\": { \"$ref\": \"\u003cmeta-data-name\u003e/\u003cnew-version\u003e.json#\" }`\n\n4. Modify the `compile.ts` script\n\n- Add the exported constant with the latest version in, and the new metadata:\n  - For example: \u003chttps://github.com/cowprotocol/app-data/pull/44/commits/aeef8a58e7bbd2a53664ce396011cb157a18406d\u003e\n\n4. Generate the typescript types\n\n- Run `yarn build`\n\n5. Make a test focusing on the new or modified meta-data:\n\n- \u003chttps://github.com/cowprotocol/app-data/pull/44/files#diff-e755a2ecce42f09829d5c7dc1de8853d1d00ef56eaadc2709601c87b9be8ddfbR556\u003e\n- Don't forget to use the right version of the schema in your test: \u003chttps://github.com/cowprotocol/app-data/pull/44/files#diff-e755a2ecce42f09829d5c7dc1de8853d1d00ef56eaadc2709601c87b9be8ddfbR11\u003e\n\n6. Create the PR and document it together with the motivation for the changes\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcowprotocol%2Fapp-data","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcowprotocol%2Fapp-data","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcowprotocol%2Fapp-data/lists"}