{"id":25916640,"url":"https://github.com/Smart123s/ItchClaim","last_synced_at":"2025-03-03T13:02:38.976Z","repository":{"id":91802924,"uuid":"502652387","full_name":"Smart123s/ItchClaim","owner":"Smart123s","description":"Automatically claim free games from itch.io","archived":false,"fork":false,"pushed_at":"2023-12-23T07:58:12.000Z","size":298,"stargazers_count":24,"open_issues_count":3,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-26T05:04:06.974Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://itchclaim.tmbpeter.com","language":"Python","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/Smart123s.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","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-12T15:22:09.000Z","updated_at":"2024-07-07T20:50:59.691Z","dependencies_parsed_at":"2023-11-07T01:18:03.103Z","dependency_job_id":"afd0d6d5-fc09-4ed4-85a3-69238bd31869","html_url":"https://github.com/Smart123s/ItchClaim","commit_stats":{"total_commits":158,"total_committers":1,"mean_commits":158.0,"dds":0.0,"last_synced_commit":"242748cdafdfb4c48bd81083b74f27bf71a6a258"},"previous_names":[],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smart123s%2FItchClaim","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smart123s%2FItchClaim/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smart123s%2FItchClaim/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Smart123s%2FItchClaim/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Smart123s","download_url":"https://codeload.github.com/Smart123s/ItchClaim/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":241670145,"owners_count":20000327,"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-03-03T13:01:21.888Z","updated_at":"2025-03-03T13:02:38.970Z","avatar_url":"https://github.com/Smart123s.png","language":"Python","funding_links":[],"categories":["Python"],"sub_categories":[],"readme":"Automatically claim free games from itch.io\n\n## Install\n```bash\npip install ItchClaim\n```\n\n## Usage\n\n```bash\nitchclaim --login \u003cusername\u003e claim\n```\nThis command logs in the user (asks for password if it's ran for the first time), refreshes the list of currently free games, and start claiming the unowned ones.\n\n## Docker\n\n```bash\ndocker run --rm -v \"\u003cpath-to-user-session-directory\u003e:/data\" ghcr.io/smart123s/itchclaim --login \u003cusername\u003e claim\n```\n\n## Advanced Usage\n\n### Logging in (via flags)\nIf you don't have access to an interactive shell, you can provide you password via flags too.\n\n```bash\nitchclaim --login \u003cusername\u003e --password \u003cpassword\u003e --totp \u003c2FA code or secret\u003e\n```\n\n### Start a never ending process that claims at a schedule\nUses cron syntax. For help, visit [crontab.guru](https://crontab.guru).\nCan be useful in docker to create an always running container.\nRecommended schedule based on [ItchClaim's online update schedule](https://github.com/Smart123s/ItchClaim/blob/6704228164afa65a6501d5a2375aa2bc0a12e117/.github/workflows/web.yml#L21): `28 0,6,12,18 * * *`.\n```bash\nitchclaim --login \u003cusername\u003e schedule --cron \"28 0,6,12,18 * * *\"\n```\n\n### Load credentials form environment variable\nIf no credentials are provided via command line arguments, the script checks the following environment variables:\n - `ITCH_USERNAME` (equivalent of `--login \u003cusername\u003e` flag)\n - `ITCH_PASSWORD` (equivalent of `--password \u003cpassword\u003e` flag)\n - `ITCH_TOTP` (equivalent of `--totp \u003c2FA code or secret\u003e` flag)\n\n\n### Scheduling using docker-compose.yml\nCreate an always running docker container, that claims new sales on a schedule.\nAfter you see `Logged in as \u003cusername\u003e` in the logs, the `ITCH_PASSWORD` and `ITCH_TOTP` environment variables can be removed, as a session gets saved to the volume (`/data`).\n```yaml\nversion: 3.8\nservices:\n  itchclaim:\n    image: ghcr.io/smart123s/itchclaim\n    container_name: itchclaim\n    command: [\"schedule\", \"--cron\", \"28 0,6,12,18 * * *\"]\n    volumes:\n      - \u003cPATH_TO_ITCHCLAIM_DATA_ON_HOST\u003e:/data:rw\n    environment:\n      ITCH_USERNAME: \"Smart123s\"\n      ITCH_PASSWORD: \"\u003cPASSWORD\u003e\"\n      ITCH_TOTP: \"\u003cTOTP/2FA\u003e\"\n    restart: unless-stopped\n```\n\n### Refresh Library\n```bash\nitchclaim --login \u003cusername\u003e refresh_library\n```\nAllows you to refresh the locally stored list of owned games. Useful if you have claimed/purchased games since you have started using the script.\n\n### Refresh sale cache\n\n#### Download cached sales from CI (recommended)\n```bash\nitchclaim refresh_from_remote_cache [--url \u003curl\u003e]\n```\nItchClaim collects new sales from itch.io every 6 hours and publishes them on GitHub. Using this method, sales don't need to be scraped by every user, greatly reducing the load on itch.io generated by the script. Also removes expired sales from disk. This command is automatically executed by the `claim` command.\n\n### Download links\n```bash\nitchclaim [--login \u003cusername\u003e] download_urls \u003cgame_url\u003e\n```\nGenerate a list of uploaded files and their download URLs for a game. These links have an expiration date. If the game doesn't require claiming, this command can be run without logging in.\n\n## CI Commands\n\n*Note: These commands were created for use on the CI, and are not recommended for general users.*\n\n#### Manually collect sales from itch.io\n```bash\nitchclaim refresh_sale_cache --dir web/data/ --sales \"[1,2,3]\" --max_pages -1\n```\nRequest details about every single itch.io, and save the $0 ones to the disk.\nThe initial run can take 12+ hours.\n\n#### Parameters\n- **dir:** Output directory\n- **sales:** (List[int]): Only refresh the sales specified in this list (Optional)\n- **max_pages:** (int): The maximum number of pages to download. Default is -1, which means unlimited (Optional)\n- **no_fail:** (bool): Continue downloading sales even if a page fails to load\n- **max_not_found_pages:** (int): The maximum number of consecutive pages that return 404 before stopping the execution. Default is 25\n\n### Generate static website\n```bash\nitchclaim generate_web --dir web/data/ --web_dir web/\n```\nGenerates a static HTML file containing a table of all the sales cached on the disk.\nThis command was created for use on the CI, and is not recommended for general users.\n\n#### Parameters\n- **dir:** Location of the data collected about games, as generated by the `refresh_sale_cache` command\n- **web_dir:** The output directory\n\n## FAQ\n\n### Is this legal?\nThis tools is not affiliated with itch.io. Using it may not be allowed, and may result in your account getting suspended or banned. Use at your own risk.\n\n### Can itch.io detect that I'm using this tool?\nYes. We explicitly let itch.io know that use the the requests were sent by this tool, using the `user-agent` header. Itch.io doesn't block using non-browser user agents (like some big corporations do), so I think that they deserve to know how their services are being used. If they want to block ItchClaim, blocking this user-agent makes it simple for them. This way, they won't have to implement additional anti-bot technologies, which would make both our and itch.io's life worse.\n\n### Why sales are not downloaded directly from itch.io?\nThe initial plan was to parse https://itch.io/games/on-sale on each run (it was even implemented in [here](https://github.com/Smart123s/ItchClaim/blob/00ddfa3dfe57c747f09486fd7791f0e1d57347f3/ItchClaim/DiskManager.py#L31-L49)), however, it turns out that only a handful of sales are listed there.\nLuckily for us, details about every sale are published at https://itch.io/s/\u003cid\\\u003e, where id is a sequentially incremented number. However, downloading data about every single sale published on itch.io generates a lot of load on their servers. To easen the load generated on itch.io by this tool, I've decide to do this scraping only once, on a remote server, and make the data publicly available.\n\n### Can ItchClaim developers see who has access the sale data?\nNo, every file on the website is hosted by GitHub via their Pages service, and no data is made available to the developers.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSmart123s%2FItchClaim","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FSmart123s%2FItchClaim","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FSmart123s%2FItchClaim/lists"}